In-Page Navigation

navigationUSWDS-derivedinteractive

A sticky sidebar table of contents auto-generated from page headings, with scroll spy highlighting.

Reference: USWDS documentation ↗

Variants

Custom Heading Levels

Section One

Content for section one.

Section Two

Content for section two.

Section Three

Content for section three.

<div style="display: grid; grid-template-columns: 1fr 15rem; gap: 2rem;">
  <main>
    <h2>Section One</h2>
    <p>Content for section one.</p>
    <h2>Section Two</h2>
    <p>Content for section two.</p>
    <h2>Section Three</h2>
    <p>Content for section three.</p>
  </main>
  <aside>
    <flex-in-page-nav data-heading-levels="h2">
      <nav class="flex-in-page-nav__nav" aria-label="Sections">
        <h4 class="flex-in-page-nav__heading">Sections</h4>
        <ul class="flex-in-page-nav__list">
        </ul>
      </nav>
    </flex-in-page-nav>
  </aside>
</div>

Default In Page Nav

Overview

This is the overview section of the page. It provides a high-level introduction to the content below.

Getting started

Here you will find instructions on how to get started with this feature.

Installation

Step-by-step installation instructions go here.

Configuration

Configuration details and options are described here.

Usage

Examples of how to use this feature in your project.

API Reference

Detailed API documentation for developers.

<div style="display: grid; grid-template-columns: 1fr 15rem; gap: 2rem;">
  <main>
    <h2>Overview</h2>
    <p>This is the overview section of the page. It provides a high-level introduction to the content below.</p>
    <h2>Getting started</h2>
    <p>Here you will find instructions on how to get started with this feature.</p>
    <h3>Installation</h3>
    <p>Step-by-step installation instructions go here.</p>
    <h3>Configuration</h3>
    <p>Configuration details and options are described here.</p>
    <h2>Usage</h2>
    <p>Examples of how to use this feature in your project.</p>
    <h2>API Reference</h2>
    <p>Detailed API documentation for developers.</p>
  </main>
  <aside>
    <flex-in-page-nav>
      <nav class="flex-in-page-nav__nav" aria-label="On this page">
        <h4 class="flex-in-page-nav__heading">On this page</h4>
        <ul class="flex-in-page-nav__list">
        </ul>
      </nav>
    </flex-in-page-nav>
  </aside>
</div>

Contract

Class mapping

USWDS	Flex	Notes
`usa-in-page-nav`	`<flex-in-page-nav> (custom element)`	Container element
`usa-in-page-nav__nav`	`.flex-in-page-nav__nav`	Sticky nav container with border-left
`usa-in-page-nav__heading`	`.flex-in-page-nav__heading`	"On this page" heading
`usa-in-page-nav__list`	`.flex-in-page-nav__list`	TOC link list
`usa-current`	`.flex-in-page-nav__link--current / [aria-current="true"]`	Active section highlight

Verified properties

font-familyfont-sizeline-heightcolortext-decorationfont-weight

Intentional differences

border-left: ours = 3px solid transparent / accent (on links), USWDS = applied via ::after pseudo-element on .usa-current

We use border-left directly on links for the active indicator; USWDS uses a ::after pseudo-element with border-radius

Behavior promises

✓ Scans page for headings and builds TOC
✓ Generates IDs for headings without them
✓ Scroll spy highlights current section via IntersectionObserver
✓ Clicking TOC link smooth scrolls to section
✓ Configurable heading levels via data-heading-levels
✓ Accessibility audit passes

Source CSS

/* flex-in-page-nav -- USWDS In-Page Navigation conformance
   Features: sticky sidebar TOC, scroll spy, active link indicator */

flex-in-page-nav {
  display: block;
}

.flex-in-page-nav__nav {
  position: sticky;
  inset-block-start: 1rem;
  border-inline-start: 1px solid var(--flex-color-border);
  padding: 0;
  max-block-size: calc(100vh - 2rem);
  overflow-y: auto;
}

.flex-in-page-nav__heading {
  font-size: 0.87rem;
  font-weight: 700;
  line-height: 1.3;
  color: var(--flex-color-text);
  margin: 0;
  padding: 0.5rem 1rem;
  letter-spacing: 0.025em;
  text-transform: uppercase;
}

.flex-in-page-nav__list {
  list-style: none;
  padding: 0;
  margin: 0;
}

.flex-in-page-nav__item {
  margin: 0;
}

.flex-in-page-nav__item--sub {
  padding-inline-start: 1rem;
}

.flex-in-page-nav__link {
  display: block;
  padding: 0.5rem 1rem;
  font-size: 1rem;
  line-height: 1.15;
  color: var(--flex-color-accent);
  text-decoration: none;
  border-inline-start: 3px solid transparent;
  margin-inline-start: -1px;

  &:hover {
    color: var(--flex-color-accent);
    text-decoration: none;
  }

  &:focus-visible {
    outline: var(--flex-focus-ring);
    outline-offset: 0;
  }
}

/* Active/current link */
.flex-in-page-nav__link--current,
.flex-in-page-nav__link[aria-current="true"] {
  color: var(--flex-color-accent);
  font-weight: 700;
  border-inline-start-color: var(--flex-color-accent);
}

/* Visited links should look muted, not visited-purple */
.flex-in-page-nav__link:visited:not(.flex-in-page-nav__link--current) {
  color: var(--flex-color-ink);
}