Outline New Alpha

Usage

Outline is an in-page table of contents for long documents, help centres, wikis and long settings pages. It lists the headings on a page, indents them by level, and highlights the section currently in view with an animated indicator as the reader scrolls.

Use it for navigation within a single page. For moving between application routes use Navigation instead, and for expandable, collapsible hierarchy reach for a tree.

Import the parts you need — each import registers its custom element:

import "@nordhealth/components/lib/Outline"
import "@nordhealth/components/lib/OutlineItem"

Then list your page's headings, linking each item to a heading id:

Composition

Outline combines a container with individual items. Each Outline Item links to a heading in your content via href and reports its nesting level (1–4), which drives its indentation.

Outline
├── OutlineItem   (level 1)
├── OutlineItem   (level 2)
└── OutlineItem   (level 1)

<nord-outline>
  <nord-outline-item href="#introduction" level="1">Introduction</nord-outline-item>
  <nord-outline-item href="#installation" level="1">Installation</nord-outline-item>
  <nord-outline-item href="#cdn" level="2">CDN</nord-outline-item>
  <nord-outline-item href="#usage" level="1">Usage</nord-outline-item>
</nord-outline>

Outline

Outline is the container. It exposes a navigation landmark with a default accessible label, owns the sliding indicator, and tracks which section is active. Each href should point at the id of a heading on the same page; clicking an item smoothly scrolls to that heading.

Outline Item

Outline Item is a single link in the list. Set its href to the target heading's fragment (for example #installation) and its level (1–4) to match the heading depth — higher levels are indented further. Its active state is managed by the parent Outline, so you don't set it yourself.

Scroll-spy

By default Outline watches the headings referenced by its items and highlights the one currently in view, animating the indicator to follow as the reader scrolls. No configuration is required — just make sure every href matches a real heading id on the page.

<!-- Headings somewhere on the page -->
<h2 id="introduction">Introduction</h2>
<h2 id="installation">Installation</h2>
<h2 id="usage">Usage</h2>

<!-- The outline, typically sticky in a sidebar -->
<nord-outline class="n:sticky n:inset-bs-m">
  <nord-outline-item href="#introduction">Introduction</nord-outline-item>
  <nord-outline-item href="#installation">Installation</nord-outline-item>
  <nord-outline-item href="#usage">Usage</nord-outline-item>
</nord-outline>

Generating from content

Instead of listing items by hand, point for at a content container and Outline builds the list automatically from that container's headings. Headings without an id are given one so they can be linked. Use heading-selector to control which headings are collected (it defaults to h1, h2, h3, h4).

<article id="docs-content">
  <h2 id="introduction">Introduction</h2>
  <h3 id="prerequisites">Prerequisites</h3>
  <h2 id="usage">Usage</h2>
</article>

<nord-outline for="docs-content"></nord-outline>

Examples

Nesting levels

Heading levels 1–4 map to progressively deeper indentation, so a long document with sub-sections stays scannable.

Density

Use density="compact" in dense sidebars where vertical space is tight.

Controlled

Set active to the id of the section you want highlighted. Providing active puts the Outline in controlled mode and disables the built-in scroll-spy, so your own logic owns the highlight. Listen to the change event to react when the active section changes.

Accessibility

• Outline renders a navigation landmark with a default accessible label (“On this page”). Override it with aria-label when a page has more than one navigation region, or to better describe the outline's scope.
• Each item's href must match the id of a real heading on the page so the link, scroll-spy and the “skip to section” behaviour all work.
• Set each item's level to match the depth of the heading it links to, so the visual nesting mirrors the document's heading structure.
• The active item is exposed with aria-current="location" for assistive technology.
• The indicator animation respects the user's prefers-reduced-motion setting.