In-page Navigation

The in-page navigation allows navigation to specific sections on a lengthy content page.

Default

Component Preview

The in-page navigation shown to the right of this content is a live example of the component. It automatically generates its links based on the h2 and h3 headings within the main content region.

This component auto-generates its content from page headings using JavaScript. The example below shows the minimum required markup.

Component Code


<div class="usa-in-page-nav-container">
  <aside class="usa-in-page-nav"></aside>
  <main id="main-content" class="main-content">
    [ Page content with h2 and h3 headings ]
  </main>
</div>

With Custom Data Attributes

Component Preview

You can customize the in-page navigation using data attributes on the aside element. This allows you to change the title text, heading levels to include, scroll offset, and more.

Component Code


<div class="usa-in-page-nav-container">
  <aside
    class="usa-in-page-nav"
    data-heading-elements="h2 h3"
    data-title-text="On this page"
    data-title-heading-level="h4"
    data-scroll-offset="48"
    data-root-margin="48px 0px -70% 0px"
    data-threshold="1"
    data-main-content-selector=".main-content"
  ></aside>
  <main id="main-content" class="main-content">
    [ Page content ]
  </main>
</div>

Guidance

When to use the in-page navigation component

Long pages.: In-page navigation can offer a substantial improvement to user experience for pages that include three or more distinct content sections or content that exceeds three or more viewport heights.

When to consider something else

Short pages.: For pages that require little or no scrolling, in-page navigation is not necessary.
Unstructured content.: Pages that lack heading-based hierarchical structures cannot use the in-page navigation component.
Infinite scrolling.: For pages that feature infinite scrolling, in-page navigation is neither a practical nor feasible feature.

Usability guidance

Display the in-page navigation to the side of the main content.: Visually, place the in-page navigation component after the main content in the language's natural reading order. For example, for a left-to-right language like English, this component goes to the right of the main content.
Make it stand out.: Site visitors should be able to quickly and easily distinguish in-page navigation from other landmarks on the page. Include borders and well-defined link active states to clearly convey the utility and purpose of the section.
Use language that matches section headings.: The text of the links displayed within the in-page navigation aside should match the heading text of the target sections. By default, the component scans the page for h2 and h3 elements within the main element.
Don't include the page h1 in the navigation.: Each page should have a single h1 to describe its contents. It would be redundant to include this heading level in the in-page navigation.
In-page navigation heading.: Inform users that they will scroll down on the same page by including in-page navigation under a descriptive title such as "On this page," "In this article," or "Table of contents."

Accessibility guidance

Allow keyboard navigation.: Users should be able to navigate between items by using the Tab key. They should also be able to activate a link when pressing Enter on their keyboard.
Keyboard users should access the in-page navigation before the main content.: When a user tabs through a page that contains the in-page navigation component, they should find the in-page navigation before the main content.
Set focus state on section target for keyboard users.: When keyboard users follow an in-page anchor link, set the focus state to the link target when the user presses the Enter key.

Using the in-page navigation component

A wrapper div with the class usa-in-page-nav-container must surround the main element.: This container enables the sticky positioning and proper layout of the in-page navigation.
A new sibling aside with the class usa-in-page-nav must precede the main element.: The aside element will be populated automatically by JavaScript based on the headings in your main content.
Customize with data attributes.: Use data attributes like data-heading-elements, data-title-text, data-scroll-offset, and data-main-content-selector to customize component behavior.

USWDS Documentation

For more guidance, view the USWDS In-page Navigation Component Documentation.

Initialization Properties

Property	Description	Default
`data-heading-elements`	The list of header levels that should be included in the link list.	`h2 h3`
`data-main-content-selector`	The element the component pulls headers from.	`<main>`
`data-title-heading-level`	The heading level of the navigation title header.	`h4`
`data-title-text`	The text of the navigation title header.	`"On this page"`
`data-scroll-offset`	Number of pixels scroll should offset from the top of the parent element.	`0`
`data-root-margin`	Observable margin around the observed root used for calculating the current active section. Use values similar to CSS margin.	`0px 0px 0px 0px`
`data-threshold`	Percentage of the scrolling section that must be in the observed area before the current section is triggered. Use a value between 0 and 1.	`1`
`data-minimum-heading-count`	The minimum number of headings needed in the content region for the component to build on the page.	`2`

Settings

Variable	Description
`$theme-in-page-nav-background-color`	Background color of the in-page navigation block.
`$theme-in-page-nav-background-padding`	Padding of the in-page navigation block.
`$theme-in-page-nav-background-radius`	The border radius of the in-page navigation block.
`$theme-in-page-nav-bar-color`	Color of the bar representing the active state of a link in the in-page navigation.
`$theme-in-page-nav-bar-width`	Width of the colored bar representing the active state of a link in the in-page navigation.
`$theme-in-page-nav-font-family`	Font family of the in-page navigation.
`$theme-in-page-nav-link-color`	The color of the link in the in-page navigation.
`$theme-in-page-nav-main-content-max-width`	Maximum width of the main element.
`$theme-in-page-nav-margin-left`	Margin to the left of in-page navigation.
`$theme-in-page-nav-margin-top`	Margin above in-page navigation.
`$theme-in-page-nav-top`	Distance from top of page to top of navigation when the sticky position is engaged on scroll.

Variants

This component has no variants. The in-page navigation is customized through data attributes rather than CSS modifier classes.