Skip to main content

An official website of the United States government

Here's how you know

Design System

An official website of the United States government

Here's how you know

Theme:

Design system switcher

Select a theme

Version:

Design system switcher

Select a version

What's new?

View code on GitHub

Theme:

Design system switcher

Select a theme

Version:

Design system switcher

Select a version

Vertical Navigation

Hierarchical, vertical navigation.

Figma logoFigmaGithubStorybook logoStorybook

Examples

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

  • If you have nested menus that are collapsible, the component automatically ensures that the aria-controls and aria-expanded attributes are set properly.
  • If the site has fewer than five pages, consider organizing the page without a navigational hierarchy.
  • 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. The Pagination component utilizes a <nav> element, so you will need to supply this prop on any page that includes both a Pagination and a VerticalNav component.
    • Don't include the word "Menu" in the label. Most screen readers will announce that already. Instead, provide more context about the menu’s contents or its location—such as "Main" or "Social".

Accessibility testing

Keyboard navigation

  • Users must be able to tab through each link using a keyboard to navigate through the vertical navigation.
  • Keyboard focus should not be trapped when navigating through vertical navigation links.
  • When using a keyboard to move through the vertical navigation, there must be a visible outline or focus indicator showing where the focus is.

Screen reader

  • Screen readers must announce the vertical navigation region and its items.
  • Screen readers must provide a direct description of links. When navigating to the vertical navigation with a screen reader, link titles must be read aloud and match the visible text on screen.
  • Screen readers must announce each link’s title, visited state, hierarchy level (e.g., parent or submenu), and the number of links present. Screen readers will also announce whether an expandable submenu is open or collapsed.

Code

React

Review Storybook for React guidance of this component.

Style customization

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__border-colorhex value: #5a5a5a--color-gray-dark
--vertical-nav-item__color--hoverhex value: #0071bc--color-primary
--vertical-nav-label__border-color--currenthex value: #0071bc--color-primary
--vertical-nav-label__colorhex value: #262626--color-base
--vertical-nav-label__color--currenthex value: #0071bc--color-primary
--vertical-nav-label-icon__colorhex value: #262626--color-base

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 Figma.
    Incomplete

On this page

Have ideas?