Side Navigation

navigationUSWDS-derived

A vertical navigation menu for navigating related pages within a section.

Variants

Default

<nav aria-label="Side navigation">
  <ul class="flex-sidenav">
    <li class="flex-sidenav__item"><a href="/page1" class="flex-sidenav__link flex-sidenav__link--current" aria-current="page">Current Page</a></li>
    <li class="flex-sidenav__item"><a href="/page2" class="flex-sidenav__link">Another Page</a></li>
    <li class="flex-sidenav__item"><a href="/page3" class="flex-sidenav__link">Third Page</a></li>
  </ul>
</nav>

Three Levels

<nav aria-label="Side navigation">
  <ul class="flex-sidenav">
    <li class="flex-sidenav__item"><a href="/page1" class="flex-sidenav__link">First Page</a></li>
    <li class="flex-sidenav__item">
      <a href="/page2" class="flex-sidenav__link">Second Page</a>
      <ul class="flex-sidenav__sublist">
        <li class="flex-sidenav__item">
          <a href="/page2/sub1" class="flex-sidenav__link">Subpage 1</a>
          <ul class="flex-sidenav__sublist">
            <li class="flex-sidenav__item"><a href="/page2/sub1/detail" class="flex-sidenav__link flex-sidenav__link--current" aria-current="page">Detail Page</a></li>
          </ul>
        </li>
        <li class="flex-sidenav__item"><a href="/page2/sub2" class="flex-sidenav__link">Subpage 2</a></li>
      </ul>
    </li>
  </ul>
</nav>

With Subnav

<nav aria-label="Side navigation">
  <ul class="flex-sidenav">
    <li class="flex-sidenav__item"><a href="/page1" class="flex-sidenav__link">First Page</a></li>
    <li class="flex-sidenav__item">
      <a href="/page2" class="flex-sidenav__link">Second Page</a>
      <ul class="flex-sidenav__sublist">
        <li class="flex-sidenav__item"><a href="/page2/sub1" class="flex-sidenav__link flex-sidenav__link--current" aria-current="page">Subpage 1</a></li>
        <li class="flex-sidenav__item"><a href="/page2/sub2" class="flex-sidenav__link">Subpage 2</a></li>
      </ul>
    </li>
    <li class="flex-sidenav__item"><a href="/page3" class="flex-sidenav__link">Third Page</a></li>
  </ul>
</nav>

Contract

Class mapping

USWDS	Flex	Notes
`usa-sidenav`	`.flex-sidenav`	Side navigation list wrapper
`usa-sidenav__item (implicit via li)`	`.flex-sidenav__item`	Navigation list item
`usa-sidenav a`	`.flex-sidenav__link`	Navigation link
`usa-current`	`.flex-sidenav__link--current`	Current page indicator
`usa-sidenav__sublist`	`.flex-sidenav__sublist`	Nested navigation sublist

Verified properties

font-familyfont-sizeline-heightlist-style-typepadding-leftborder-bottom-widthborder-bottom-styledisplaytext-decoration-line

Intentional differences

border-color: ours = var(--flex-color-border), USWDS = #dfe1e2

We use our semantic border token

Behavior promises

○ Current page has left border accent indicator
○ Hover state changes background and text color
○ Nested sublists increase indentation

Source CSS

/* flex-sidenav — USWDS Side Navigation conformance
   Features: 1-3 level nesting, current page indicator */

.flex-sidenav {
  margin-block: 0;
  list-style-type: none;
  padding-inline-start: 0;
  font-size: 1.06rem;
  line-height: 1.3;
  border-block-end: 1px solid var(--flex-color-border);

  > li {
    margin-block-end: 0;
    max-inline-size: unset;
  }
}

/* --- Item --- */

.flex-sidenav__item {
  border-block-start: 1px solid var(--flex-color-border);
}

/* --- Link --- */

.flex-sidenav__link {
  display: block;
  padding: 0.5rem 1rem;
  text-decoration: none;
  color: var(--flex-color-text-muted);

  &:hover {
    background-color: var(--flex-color-bg-subtle);
    text-decoration: none;
    color: var(--flex-color-link);
  }

  &:focus {
    outline-offset: 0;
    outline: 0.25rem solid var(--flex-color-focus);
  }
}

/* --- Current page indicator --- */

.flex-sidenav__link--current {
  position: relative;
  color: var(--flex-color-link);
  font-weight: 700;

  &::after {
    background-color: var(--flex-color-link);
    border-radius: 99rem;
    content: "";
    display: block;
    position: absolute;
    inset-block: 0.25rem;
    inline-size: 0.25rem;
    inset-inline-start: 0;
  }
}

/* --- Sublist (nested level 1) --- */

.flex-sidenav__sublist {
  list-style-type: none;
  padding-inline-start: 0;
  margin: 0;
  font-size: 1rem;

  > li {
    margin-block-end: 0;
    max-inline-size: unset;
  }

  .flex-sidenav__item {
    border-block-start: 1px solid var(--flex-color-border);
    font-size: 0.93rem;
  }

  .flex-sidenav__link {
    padding-inline-start: 2rem;
  }

  .flex-sidenav__link--current::after {
    display: none;
  }

  /* --- Sublist level 2 (nested within sublist) --- */

  .flex-sidenav__sublist .flex-sidenav__link {
    padding-inline-start: 3rem;
  }
}