In-page navigation

Help visitors jump between sections of a long page with in-page navigation.

Examples

Default

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px

Overview

Start with the program overview and the services available to applicants.

Eligibility

Check the eligibility requirements before preparing an application.

How to apply

Gather the required documents and submit your application.

Next steps

Review what happens after you submit your application.

in-page-navigation-demo.tsx

import type { InPageNavHeading } from '@uswds-tailwind/react'
import { InPageNav } from '@uswds-tailwind/react'
import * as React from 'react'

const headings: InPageNavHeading[] = [
  { href: '#nav-overview', label: 'Overview', depth: 1 },
  { href: '#nav-eligibility', label: 'Eligibility', depth: 2 },
  { href: '#nav-application', label: 'How to apply', depth: 2 },
  { href: '#nav-next-steps', label: 'Next steps', depth: 1 },
]

export default function InPageNavigationDemo() {
  const scrollRef = React.useRef<HTMLDivElement>(null)

  return (
    <div className="flex flex-col gap-8 tablet:flex-row">
      <div className="tablet:w-64 tablet:shrink-0 tablet:order-last">
        <InPageNav.Root headings={headings}>
          <InPageNav.Scrollspy root={scrollRef} />
          <InPageNav.Heading><h4>On this page</h4></InPageNav.Heading>
          <InPageNav.List>
            {({ headings }) => headings.map(heading => (
              <InPageNav.Item key={heading.href}>
                <InPageNav.Link href={heading.href} depth={heading.depth}>
                  {heading.label}
                </InPageNav.Link>
              </InPageNav.Item>
            ))}
          </InPageNav.List>
        </InPageNav.Root>
      </div>
      <div ref={scrollRef} className="flex-1 space-y-8 max-h-96 overflow-auto border">
        <section className="min-h-40">
          <h4 id="nav-overview" className="text-xl font-bold">Overview</h4>
          <p>Start with the program overview and the services available to applicants.</p>
        </section>
        <section className="min-h-40">
          <h4 id="nav-eligibility" className="text-xl font-bold">Eligibility</h4>
          <p>Check the eligibility requirements before preparing an application.</p>
        </section>
        <section className="min-h-40">
          <h4 id="nav-application" className="text-xl font-bold">How to apply</h4>
          <p>Gather the required documents and submit your application.</p>
        </section>
        <section className="min-h-40">
          <h4 id="nav-next-steps" className="text-xl font-bold">Next steps</h4>
          <p>Review what happens after you submit your application.</p>
        </section>
      </div>
    </div>
  )
}

Items shortcut

InPageNav.Items renders an Item and Link for each heading. Inside InPageNav.List, this:

<InPageNav.List>
  <InPageNav.Items />
</InPageNav.List>

is shorthand for the render function used in the full example above:

<InPageNav.List>
  {({ headings }) => headings.map(heading => (
    <InPageNav.Item key={heading.href}>
      <InPageNav.Link href={heading.href} depth={heading.depth}>
        {heading.label}
      </InPageNav.Link>
    </InPageNav.Item>
  ))}
</InPageNav.List>

Component API

Root receives the page headings. Put List and optional Heading inside it; Items can render links from the headings array.

Root`<nav>`

Owns the heading list and active destination.

Prop	Type	Description
`headings`	`InPageNavHeading[] (required)`	Each heading has an anchor href, label, and depth from 1 through 6.
`activeHref`	`string`	Initial active anchor.
`onActiveChange`	`(href: string) => void`	Called when the active heading changes.

Heading`<div>`

Displays a label for the navigation.

List`<ul>`

Contains navigation items.

Prop	Type	Description
`children`	`ReactNode \| ({ headings, activeHref }) => ReactNode`	Renders links directly or from heading state.

Item`<li>`

Wrap one Link inside the list.

Link`<a>`

Point href to a heading anchor on this page.

Prop	Type	Description
`href`	`string (required)`	Anchor target.
`depth`	`number`	Heading level used to style indentation.

Attribute	Value	Purpose
`data-active`	`Present for the active link`	Highlights the current section.
`data-depth`	`Heading depth`	Styles nesting.
`data-primary`	`Present at the shallowest depth`	Styles top-level items.

Scrollspy

Observes heading intersections and updates the active destination.

Prop	Type	Description
`root`	`RefObject<Element \| null>`	Optional scroll container.
`options`	`IntersectionObserverInit without root`	Intersection observer settings.

Items

Renders Item and Link for each supplied heading.