In-Page Navigation

A JavaScript-powered navigation component that automatically generates a table of contents from page headings, following USWDS patterns. The component uses Intersection Observer to highlight the current section as users scroll.

Props

Prop	Default	Description
`title_text`	`On this page`	Text for the navigation title
`title_heading_level`	`h4`	Heading level for the navigation title (h1-h6)
`scroll_offset`	`0`	Offset from top when scrolling to sections (in pixels)
`root_margin`	`0px 0px 0px 0px`	Root margin for Intersection Observer
`threshold`	`1`	Visibility threshold for Intersection Observer (0-1)
`content_id`	`main-content`	ID attribute for the main content element
`extra_classes`		Additional CSS classes for the container

Slots

Slot	Description
(default)	Main content with headings (h1, h2, h3) that will be tracked

How It Works

The in-page navigation component: 1. Automatically scans the content for h2 and h3 headings 2. Generates a table of contents navigation sidebar 3. Uses Intersection Observer to track which section is currently visible 4. Highlights the current section in the navigation 5. Provides smooth scrolling to sections when clicked

Example Usage

Basic In-Page Navigation

<c-in_page_nav>
    <h1>Page Title</h1>

    <h2>Introduction</h2>
    <p>Introduction content goes here...</p>

    <h2>Getting Started</h2>
    <p>Getting started content...</p>

    <h3>Installation</h3>
    <p>Installation instructions...</p>

    <h3>Configuration</h3>
    <p>Configuration details...</p>

    <h2>Examples</h2>
    <p>Example content...</p>
</c-in_page_nav>

Custom Title and Heading Level

<c-in_page_nav
    title_text="Page contents"
    title_heading_level="h3"
>
    <h1>Documentation</h1>

    <h2>Overview</h2>
    <p>Overview content...</p>

    <h2>API Reference</h2>
    <p>API documentation...</p>

    <h3>Methods</h3>
    <p>Method descriptions...</p>

    <h3>Properties</h3>
    <p>Property descriptions...</p>
</c-in_page_nav>

With Custom Scroll Offset

<c-in_page_nav
    title_text="Table of contents"
    scroll_offset="100"
>
    <h1>User Guide</h1>

    <h2>Chapter 1</h2>
    <p>Chapter content...</p>

    <h2>Chapter 2</h2>
    <p>Chapter content...</p>
</c-in_page_nav>

Usage Notes

The component automatically generates navigation from h2 and h3 headings in your content
Headings must have text content to appear in the navigation
The scroll_offset prop is useful when you have a fixed header
The component requires the USWDS JavaScript to be loaded and initialized
The navigation will be empty if no h2 headings are found in the content
Use semantic heading levels (don't skip from h2 to h4)

{% load cotton %}

<div class="component-variants">
    <h1>In-Page Navigation Component</h1>

    {% for variant in variants %}
    <div class="component-variant">
        <h2 class="variant-title">{{ variant.title }}</h2>

        {% cotton in_page_nav title_text="{{ variant.title_text }}" title_heading_level="{{ variant.title_heading_level }}" scroll_offset="{{ variant.scroll_offset }}" content_id="{{ variant.content_id }}" %}
            <h1>{{ variant.page_title }}</h1>

            {% for section in variant.sections %}
            <h2>{{ section.heading }}</h2>
            {% for paragraph in section.paragraphs %}
            <p>{{ paragraph }}</p>
            {% endfor %}

            {% if section.subsections %}
                {% for subsection in section.subsections %}
                <h3>{{ subsection.heading }}</h3>
                {% for paragraph in subsection.paragraphs %}
                <p>{{ paragraph }}</p>
                {% endfor %}
                {% endfor %}
            {% endif %}
            {% endfor %}
        {% endcotton %}
    </div>
    {% endfor %}
</div>

name: In-Page Navigation
context:
  variants:
    - title: "Default In-Page Navigation"
      title_text: "On this page"
      title_heading_level: "h4"
      scroll_offset: "0"
      content_id: "main-content"
      page_title: "Sample in-page navigation page"
      sections:
        - heading: "Lorem ipsum dolor"
          paragraphs:
            - "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Morbi commodo, ipsum sed pharetra gravida, orci magna rhoncus neque, id pulvinar odio lorem non turpis. Nullam sit amet enim."
            - "Suspendisse id velit vitae ligula volutpat condimentum. Aliquam erat volutpat. Sed quis velit. Nulla facilisi. Nulla libero. Vivamus pharetra posuere sapien."
        - heading: "Consectetuer adipiscing elit"
          paragraphs:
            - "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Morbi commodo, ipsum sed pharetra gravida, orci magna rhoncus neque, id pulvinar odio lorem non turpis."
            - "Nullam sit amet enim. Suspendisse id velit vitae ligula volutpat condimentum. Aliquam erat volutpat. Sed quis velit. Nulla facilisi."
          subsections:
            - heading: "Nullam sit amet enim"
              paragraphs:
                - "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Morbi commodo, ipsum sed pharetra gravida, orci magna rhoncus neque, id pulvinar odio lorem non turpis."
            - heading: "Vivamus pharetra posuere sapien"
              paragraphs:
                - "Suspendisse id velit vitae ligula volutpat condimentum. Aliquam erat volutpat. Sed quis velit. Nulla facilisi. Nulla libero."
            - heading: "Suspendisse id velit"
              paragraphs:
                - "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Morbi commodo, ipsum sed pharetra gravida, orci magna rhoncus neque."
            - heading: "Orci magna rhoncus neque"
              paragraphs:
                - "Nullam sit amet enim. Suspendisse id velit vitae ligula volutpat condimentum. Aliquam erat volutpat."
        - heading: "Aliquam erat volutpat"
          paragraphs:
            - "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Morbi commodo, ipsum sed pharetra gravida, orci magna rhoncus neque."
            - "Nullam sit amet enim. Suspendisse id velit vitae ligula volutpat condimentum. Aliquam erat volutpat. Sed quis velit."
          subsections:
            - heading: "Vitae ligula"
              paragraphs:
                - "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Morbi commodo, ipsum sed pharetra gravida, orci magna rhoncus neque, id pulvinar odio lorem non turpis."
                - "Nullam sit amet enim. Suspendisse id velit vitae ligula volutpat condimentum. Aliquam erat volutpat. Sed quis velit. Nulla facilisi."

    - title: "Custom Title In-Page Navigation"
      title_text: "Page contents"
      title_heading_level: "h3"
      scroll_offset: "0"
      content_id: "page-content"
      page_title: "Documentation page"
      sections:
        - heading: "Getting started"
          paragraphs:
            - "This section covers the basics of getting started with the component. Follow these steps to integrate it into your project."
        - heading: "Configuration"
          paragraphs:
            - "Learn how to configure the component to meet your specific needs. There are several options available."
          subsections:
            - heading: "Basic options"
              paragraphs:
                - "These are the most commonly used configuration options that you'll need to set up."
            - heading: "Advanced options"
              paragraphs:
                - "For more complex use cases, these advanced options provide additional control."
        - heading: "Examples"
          paragraphs:
            - "Here are some practical examples showing how to use the component in real-world scenarios."