Vertical navigation

Jump to guidance View related guidance in the U.S. Web Design System

Hierarchical, vertical navigation.

Code snippet

<nav>
  <ul class="ds-c-vertical-nav">
    <li class="ds-c-vertical-nav__item">
      <a class="ds-c-vertical-nav__label" href="javascript:void(0);"> Parent link </a>
    </li>
    <li class="ds-c-vertical-nav__item">
      <button
        class="ds-c-vertical-nav__label ds-c-vertical-nav__label--current ds-c-vertical-nav__label--parent"
        title="Collapse sub-navigation"
        aria-expanded="true"
      >
        Current page

        <svg
          aria-labelledby="icon-46__title"
          aria-hidden="true"
          class="ds-c-icon ds-c-icon--arrow ds-c-icon--arrow-up"
          focusable="false"
          id="icon-46"
          role="img"
          viewBox="0 0 320 512"
          xmlns="http://www.w3.org/2000/svg"
        >
          <title id="icon-46__title">up arrow</title>
          <path
            fill="currentColor"
            d="M285.476 272.971L91.132 467.314c-9.373 9.373-24.569 9.373-33.941 0l-22.667-22.667c-9.357-9.357-9.375-24.522-.04-33.901L188.505 256 34.484 101.255c-9.335-9.379-9.317-24.544.04-33.901l22.667-22.667c9.373-9.373 24.569-9.373 33.941 0L285.475 239.03c9.373 9.372 9.373 24.568.001 33.941z"
          ></path>
        </svg>
      </button>
      <ul class="ds-c-vertical-nav__subnav">
        <li class="ds-c-vertical-nav__item">
          <a class="ds-c-vertical-nav__label" href="javascript:void(0);"> Child link </a>
        </li>
        <li class="ds-c-vertical-nav__item">
          <button
            class="ds-c-vertical-nav__label ds-c-vertical-nav__label--current ds-c-vertical-nav__label--parent"
            title="Collapse sub-navigation"
            aria-expanded="true"
          >
            Child link
            <svg
              aria-labelledby="icon-46__title"
              aria-hidden="true"
              class="ds-c-icon ds-c-icon--arrow ds-c-icon--arrow-up"
              focusable="false"
              id="icon-46"
              role="img"
              viewBox="0 0 320 512"
              xmlns="http://www.w3.org/2000/svg"
            >
              <title id="icon-46__title">up arrow</title>
              <path
                fill="currentColor"
                d="M285.476 272.971L91.132 467.314c-9.373 9.373-24.569 9.373-33.941 0l-22.667-22.667c-9.357-9.357-9.375-24.522-.04-33.901L188.505 256 34.484 101.255c-9.335-9.379-9.317-24.544.04-33.901l22.667-22.667c9.373-9.373 24.569-9.373 33.941 0L285.475 239.03c9.373 9.372 9.373 24.568.001 33.941z"
              ></path>
            </svg>
          </button>
          <ul class="ds-c-vertical-nav__subnav">
            <li class="ds-c-vertical-nav__item">
              <a class="ds-c-vertical-nav__label" href="javascript:void(0);"> Grandchild link </a>
            </li>
            <li class="ds-c-vertical-nav__item">
              <a
                class="ds-c-vertical-nav__label ds-c-vertical-nav__label--current"
                href="javascript:void(0);"
              >
                Grandchild link
              </a>
            </li>
          </ul>
        </li>
        <li class="ds-c-vertical-nav__item">
          <a class="ds-c-vertical-nav__label" href="javascript:void(0);"> Child link </a>
        </li>
      </ul>
    </li>
    <li class="ds-c-vertical-nav__item">
      <a class="ds-c-vertical-nav__label" href="javascript:void(0);"> Parent link </a>
    </li>
  </ul>
</nav>

React

`<VerticalNav>`

View source file

A VerticalNav component accepts list items as a JSON object and includes additional functionality like collapsible nested menus.

New tab

Code snippet

// Mock react-router example
const Link = ({ className, ...props }) => (
  // <Link to={props.href} {...props}>{props.children}</Link>
  <a className={classNames(className, 'special-link')} {...props}>
    {props.children}
  </a>
);
Link.propTypes = { children: PropTypes.node };

ReactDOM.render(
  <VerticalNav
    selectedId="team"
    ariaNavLabel="Primary"
    items={[
      {
        label: 'Parent link',
        url: '#!',
        id: 'parentlink1',
      },
      {
        label: 'Current page',
        selected: true,
        items: [
          {
            id: 'childlink1',
            label: 'Child link',
            url: '#!',
          },
          {
            label: 'Child link',
            selected: true,
            component: Link,
            items: [
              {
                id: 'grandchildlink1',
                label: 'Grandchild link',
                url: '#!',
              },
              {
                id: 'grandchildlink2',
                label: 'Grandchild link',
                url: '#!',
                selected: true,
              },
            ],
          },
          {
            id: 'childlink3',
            label: 'Child link',
            url: '#!',
          },
        ],
      },
      {
        label: 'Parent link',
        url: '#!',
        id: 'parentlink2',
      },
    ]}
  />,
  document.getElementById('js-example')
);

Props

React Properties Documentation
Name	Type	Default	Description
`ariaNavLabel`	`string`		An optional arial label for the `<nav>` element in this component. This prop is necessary when there is more than one nav element on a page.
`className`	`string`		Additional classes to be added to the root element
`collapsed`	`boolean`	`false`	Whether or not the menu is in a collapsed state
`component`	`any`		When provided, this will render the passed in component for all `VerticalNavItem`s. This is useful when integrating with React Router's `<Link>` or using your own custom component. If more specific control is needed, each `VerticalNavItem` object also accepts a `component` prop.
`selectedId`	`string`		The `id` of the selected `VerticalNavItem`. This will also set the `selected` prop on the item's parents.
`id`	`string`
`items` Required	`VerticalNavItemProps[]`		An array of `VerticalNavItem` data objects
`nested`	`boolean`		Indicates this list is nested within another nav item.
`onLinkClick`	`(evt: MouseEvent<Element, MouseEvent> \| KeyboardEvent<Element>, id: string, url: string) => any`		Called when one of the nav links is clicked, with the following arguments: `SyntheticEvent`, `id`, `url`

React

`<VerticalNavItem>`

View source file

Props

React Properties Documentation
Name	Type	Default	Description
`ariaCollapsedStateButtonLabel`	`string`	`Expand sub-navigation`	Aria label for the toggle button when the sub-navigation is collapsed
`ariaExpandedStateButtonLabel`	`string`	`Collapse sub-navigation`	Aria label for the toggle button when the sub-navigation is expanded
`className`	`string`		Additional classes to be added to the root element
`component`	`any`		When provided, this will render the passed in component. This is useful when integrating with React Router's `<Link>` or using your own custom component.
`defaultCollapsed`	`boolean`	`false`	Whether or not the item's sub-navigation is in a collapsed state by default
`onClick`	`(evt: MouseEvent<Element, MouseEvent> \| KeyboardEvent<Element>, id: string, url: string) => any`		Called when the link is clicked, with the following arguments: `SyntheticEvent`, `id`, `url`. This takes precedence over the `VerticalNav` `onLinkClick` prop
`onSubnavToggle`	`(id: string, collapsed: boolean) => any`		Called when this item's subnav is collapsed or expanded, with the following arguments: `id`, `collapsed`
`id`	`string`		Optional identifier. This can be handy if you're passing in an `onClick` handler. A unique ID will be generated if one isn't provided.
`items`	`any[]`		An array of nested `VerticalNavItem` data objects to be rendered in a sub-navigation list.
`label` Required	`ReactNode`		Text to render for this nav item
`url`	`string`		A URL to navigate to if this item is a link
`selected`	`boolean`		If this item is currently selected

Guidance

When to use

To display a navigational hierarchy with one to three levels.
To display the “sub-navigation” within a section of the website.

When to consider alternatives

If the site has fewer than five pages, consider organizing the page without a navigational hierarchy.
If your page already has a horizontal and vertical navigation bar, consider ways to simplify your navigation system.
If your content is within a frame or sub-area of a page, consider ways to simplify your navigation system.

Usage

Indicate where a user is within the navigational hierarchy. Use the .ds-c-vertical-nav__label--current modifier to show users which page they have navigated to.
Keep the navigation links short and follow sentence case. They can be shorter derivatives of page titles themselves.
If the navigation hierarchy is too long, users may miss items at the bottom. If it’s too deep, users may miss items that require too many clicks. Usability test to find the right balance between breadth and depth.

Accessibility

Users should be able to tab through each link.
If you have nested menus that are collapsible, ensure the toggle button has its aria-controls and aria-expanded attributes set. This is done automatically for you if you're using the React components.
If your navigation list is longer than 3 items, consider using a skip navigation link. This allows screen reader and keyboard users to skip to the main content area(s).
If a skip navigation link is not an option, consider using:
- A valid, descriptive page header
- Landmark regions like <header>, <main>, <aside>, <footer>
When naming the optional ariaNavLabel prop, keep in mind:
- This prop is necessary only when there is more than one nav element on a page.
- Don't include the word "Menu" in the label. Most screen readers will announce that information already. Instead, provide more context to what's in the menu and/or its location. Like "Main" or "Social".

Related patterns

Tabs

CMS Design System

Vertical navigation

`<VerticalNav>`

Props

`<VerticalNavItem>`

Props

Guidance

When to use

When to consider alternatives

Usage

Accessibility

Related patterns

Learn more