Components

Side navigation

Hierarchical, vertical navigation to place at the side of a page.

Passed WCAG 2.1 AA 

<div class="grid-row grid-gap">
  <div class="tablet:grid-col-4 margin-bottom-4 tablet:margin-bottom-0">
    <nav aria-label="Side navigation,">
  <ul class="usa-sidenav">
    <li class="usa-sidenav__item">
      <a href="javascript:void(0);" class="usa-current">Current page</a>
    </li>
    <li class="usa-sidenav__item">
      <a href="javascript:void(0);">Parent link</a>
    </li>
    <li class="usa-sidenav__item">
      <a href="javascript:void(0);">Parent link</a>
    </li>
  </ul>
</nav>
  </div>

  <div class="tablet:grid-col-4 margin-bottom-4 tablet:margin-bottom-0">
    <nav aria-label="Side navigation,,">
  <ul class="usa-sidenav">
    <li class="usa-sidenav__item">
      <a href="javascript:void(0);">Parent link</a>
    </li>
    <li class="usa-sidenav__item">
      <a href="javascript:void(0);" class="usa-current">Current page</a>
      <ul class="usa-sidenav__sublist">
        <li class="usa-sidenav__item">
          <a href="javascript:void(0);">Child link</a>
        </li>
        <li class="usa-sidenav__item">
          <a href="javascript:void(0);">Child link</a>
        </li>
        <li class="usa-sidenav__item">
          <a href="javascript:void(0);" class="usa-current">Child link</a>
        </li>
      </ul>
    </li>
    <li class="usa-sidenav__item">
      <a href="javascript:void(0);">Parent link</a>
    </li>
  </ul>
</nav>
  </div>

  <div class="tablet:grid-col-4">
    <nav aria-label="Side navigation,,,">
  <ul class="usa-sidenav">
    <li class="usa-sidenav__item">
      <a href="javascript:void(0);">Parent link</a>
    </li>
    <li class="usa-sidenav__item">
      <a href="javascript:void(0);" class="usa-current">Current page</a>
      <ul class="usa-sidenav__sublist">
        <li class="usa-sidenav__item">
          <a href="javascript:void(0);">Child link</a>
        </li>
        <li class="usa-sidenav__item">
          <a href="javascript:void(0);">Child link</a>
          <ul class="usa-sidenav__sublist">
            <li class="usa-sidenav__item">
              <a href="javascript:void(0);">Grandchild link</a>
            </li>
            <li class="usa-sidenav__item">
              <a href="javascript:void(0);" class="usa-current"
                >Grandchild link</a
              >
            </li>
            <li class="usa-sidenav__item">
              <a href="javascript:void(0);">Grandchild link</a>
            </li>
          </ul>
        </li>
        <li class="usa-sidenav__item">
          <a href="javascript:void(0);">Child link</a>
        </li>
      </ul>
    </li>
    <li class="usa-sidenav__item">
      <a href="javascript:void(0);">Parent link</a>
    </li>
  </ul>
</nav>
  </div>
</div>

Guidance

When to use the side navigation component

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

When to consider something else

  • Small site. If the site has fewer than five pages, consider organizing the page without a navigational hierarchy.
  • Existing navigation. If your page already has a horizontal and vertical navigation bar, consider ways to simplify your navigation system.

Usability guidance

  • Show the current page. Indicate where a user is within the navigational hierarchy. Use the “active” state to show users which page they have navigated to.
  • Keep the navigation links short. They can be shorter derivatives of page titles themselves.
  • Always test your navigation. 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 guidance

Test the side navigation component in your own project.

USWDS tested the side navigation component for accessibility. You should test your implementation, too.

Use side navigation accessibility tests
  • The width of the current menu item’s highlight border is set with the $theme-sidenav-current-border-width variable.

Using the side navigation component

Side navigation settings

Variable Description
$theme-sidenav-current-border-width

Width of the current section indicator.
$theme-sidenav-font-family

Font family of the side navigation.
$theme-sidenav-reorder

Reorder Documentation template sidenav with CSS. Favor code example in Documentation template instead.

Side navigation variants

This component has no variants.

Accessibility test status

The USWDS team did 10 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
10 5 0 5 0

Overview of recent accessibility test results:

  • Passed: 5
  • Passed with exceptions: 0
  • Conditional: 5
  • Failed: 0

Learn more on the side navigation accessibility tests page.

Package

  • Package usage: @forward "usa-sidenav";
  • Dependencies: uswds-fonts

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-10-16 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2864

2024-03-11 3.8.0
  • Accessibility
  • Styles
  • Settings
 No

Added a new fallback setting for sidenavs in Documentation template. The new setting $theme-sidenav-reorder reorders the sidenav with CSS. Users should follow new markup recommendation in Documentation template’s code example to avoid accessibility issues. More information: uswds#5809

2022-08-05 3.1.0
  • Accessibility
  • Guidance
  • JavaScript
  • Markup
 Breaking

Breaking Added type="button" to all non-form buttons to prevent default submit behaviors. This allowed us to remove preventDefault() from the relevant component JavaScript. More information: uswds#4695

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2021-04-28 2.11.2
  • Styles
 No

Fixed color of active parents in side navigation. Fixed a regression where parent items in usa-sidenav no longer receive primary color. More information: uswds#4163