Skip to main content
U.S. Flag

An official website of the United States government

CMS Design System

Vertical Navigation

Hierarchical, vertical navigation.

Examples

Loading

Code

React

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

React Properties Documentation
NameTypeDefaultDescription
ariaNavLabelstringAn 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.
classNamestringAdditional classes to be added to the root element
collapsedbooleanfalseWhether or not the menu is in a collapsed state
componentanyWhen provided, this will render the passed in component for all VerticalNavItems. 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.
selectedIdstringThe id of the selected VerticalNavItem. This will also set the selected prop on the item's parents.
idstring
itemsrequiredVerticalNavItemProps[]An array of VerticalNavItem data objects
nestedbooleanIndicates this list is nested within another nav item.
onLinkClick(evt: MouseEvent<Element, MouseEvent> | KeyboardEvent<Element>, id: string, url: string) => anyCalled when one of the nav links is clicked, with the following arguments: SyntheticEvent, id, url

<VerticalNavItem> component

React Properties Documentation
NameTypeDefaultDescription
ariaCollapsedStateButtonLabelstringExpand sub-navigationAria label for the toggle button when the sub-navigation is collapsed
ariaExpandedStateButtonLabelstringCollapse sub-navigationAria label for the toggle button when the sub-navigation is expanded
classNamestringAdditional classes to be added to the root element
componentanyWhen provided, this will render the passed in component. This is useful when integrating with React Router's <Link> or using your own custom component.
defaultCollapsedbooleanfalseWhether 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) => anyCalled 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) => anyCalled when this item's subnav is collapsed or expanded, with the following arguments: id, collapsed
idstringOptional identifier. This can be handy if you're passing in an onClick handler. A unique ID will be generated if one isn't provided.
itemsany[]An array of nested VerticalNavItem data objects to be rendered in a sub-navigation list.
labelrequiredReactNodeText to render for this nav item
urlstringA URL to navigate to if this item is a link
selectedbooleanIf this item is currently selected

Styles

The following CSS variables can be overridden to customize VerticalNav components:

CSS variables for vertical-nav
VariableDefault Core Theme Value
--vertical-nav-item__background-color--hoverhex value: #f2f2f2--color-gray-lightest
--vertical-nav-item__color--hoverhex value: #0071bc--color-primary
--vertical-nav-item__border-colorhex value: #5a5a5a--color-gray-dark
--vertical-nav-label__colorhex value: #262626--color-base
--vertical-nav-label-icon__colorhex value: #262626--color-base
--vertical-nav-label__border-color--currenthex value: #0071bc--color-primary
--vertical-nav-label__color--currenthex value: #0071bc--color-primary

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".

Learn more

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Incomplete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Complete

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Not applicable

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete