Skip to content
Norn
Menu

norn-toc

The page's contents: a link to each section heading, as an outline. Each heading sits in a nested list under the nearest heading above it with a lower level, so an h3 is listed inside the h2 it belongs to and a skipped level adds no empty list. The input stays flat. Data-driven, from headings (registered as nornHeadings), so it stays in step with the page. Its script marks the section in view with aria-current="location". The marked link takes the accent color. With fewer than two headings it renders nothing. The title is the summary of a <details>, shown open and unclickable unless fold says otherwise: then the list folds away under the title. norn-docs passes narrow. A browser without ::details-content always shows the fold.

<norn-toc> a landmark, from @allons-y/webc-patterns

Examples

Color scheme
Width

Open on its own

Source
<norn-sidebar-layout>
	<norn-toc
		slot="nav"
		:@items="[
			{ id: 'install', text: 'Install', level: 2 },
			{ id: 'with-npm', text: 'With npm', level: 3 },
			{ id: 'usage', text: 'Usage', level: 2 }
		]"
	></norn-toc>
	<h1>Getting started</h1>
	<norn-rich-text>
		<p>Install the project, then run it once to see it work. The steps below take a few minutes on a new machine.</p>
		<norn-heading-anchor @slug="install">Install</norn-heading-anchor>
		<p>The package needs Node 24 or later. Check the version with <code>node --version</code> first.</p>
		<p>Add the package to the project as a development dependency, so it stays out of the production install.</p>
		<norn-heading-anchor @slug="with-npm" :@level="3">With npm</norn-heading-anchor>
		<p>Run <code>npm install --save-dev @example/core</code> in the project folder. npm writes the version to the lockfile.</p>
		<p>Commit the lockfile with the change, so every machine installs the same version.</p>
		<norn-heading-anchor @slug="usage">Usage</norn-heading-anchor>
		<p>Import <code>greet</code> from the package and call it with a name. It returns the greeting as a string.</p>
		<p>Pass a second argument to change the greeting, such as <code>"Good morning"</code> in place of <code>"hello"</code>.</p>
		<p>Call it as often as needed: it keeps no state between calls.</p>
	</norn-rich-text>
</norn-sidebar-layout>
Color scheme
Width

Open on its own

Source
<norn-sidebar-layout>
	<norn-toc
		slot="nav"
		:@items="[
			{ id: 'install', text: 'Install', level: 2 },
			{ id: 'with-npm', text: 'With npm', level: 3 },
			{ id: 'pinned', text: 'Pinned versions', level: 4 },
			{ id: 'ranges', text: 'Version ranges', level: 5 },
			{ id: 'carets', text: 'Caret ranges', level: 6 }
		]"
	></norn-toc>
	<h1>Getting started</h1>
	<norn-rich-text>
		<p>Install the project, then run it once to see it work. The steps below take a few minutes on a new machine.</p>
		<norn-heading-anchor @slug="install">Install</norn-heading-anchor>
		<p>The package needs Node 24 or later. Check the version with <code>node --version</code> first.</p>
		<norn-heading-anchor @slug="with-npm" :@level="3">With npm</norn-heading-anchor>
		<p>Run <code>npm install --save-dev @example/core</code> in the project folder. npm writes the version to the lockfile.</p>
		<norn-heading-anchor @slug="pinned" :@level="4">Pinned versions</norn-heading-anchor>
		<p>Pass an exact version, such as <code>@example/core@1.2.0</code>, to install that release and no other.</p>
		<norn-heading-anchor @slug="ranges" :@level="5">Version ranges</norn-heading-anchor>
		<p>A range lets npm pick the newest release that fits, each time the lockfile is updated.</p>
		<norn-heading-anchor @slug="carets" :@level="6">Caret ranges</norn-heading-anchor>
		<p>A caret range, such as <code>^1.2.0</code>, accepts any 1.x release from 1.2.0 up.</p>
		<p>npm writes a caret range by default when it adds a package.</p>
	</norn-rich-text>
</norn-sidebar-layout>
Color scheme
Width

Open on its own

Source
<norn-sidebar-layout>
	<norn-toc
		slot="nav"
		:@items="[
			{ id: 'overview', text: 'Overview', level: 3 },
			{ id: 'setup', text: 'Setup', level: 2 },
			{ id: 'tokens', text: 'Design tokens', level: 4 },
			{ id: 'usage', text: 'Usage', level: 2 }
		]"
	></norn-toc>
	<h1>Getting started</h1>
	<norn-rich-text>
		<p id="overview">An overview of the project and what it does.</p>
		<p>Install the project, then run it once to see it work. The steps below take a few minutes on a new machine.</p>
		<p id="setup">Set up the project folder before the first build.</p>
		<p>The package needs Node 24 or later. Check the version with <code>node --version</code> first.</p>
		<p id="tokens">Design tokens set the colors, the type, and the spacing.</p>
		<p>Override a token in the project's own stylesheet, and every component follows it.</p>
		<p id="usage">Import the package and call it with a name.</p>
		<p>It returns the greeting as a string, and keeps no state between calls.</p>
	</norn-rich-text>
</norn-sidebar-layout>
Color scheme
Width

Open on its own

Source
<div style="display: grid; gap: 1.5rem">
	<div style="display: grid; gap: 0.5rem">
		<p><code>fold = always</code></p>
		<div>
			<norn-toc @fold="always"></norn-toc>
		</div>
	</div>
	<div style="display: grid; gap: 0.5rem">
		<p><code>fold = narrow</code></p>
		<div>
			<norn-toc @fold="narrow"></norn-toc>
		</div>
	</div>
</div>

Props

Write them with the @ prefix, and :@ for an expression.

NameTypeDescription
@items required { id: string, text: string, level: number }[] The page's headings, in order.
@fold string When the list folds under its title: always, or narrow, while the nearest container is narrower than 60rem. Unset, it never folds.

Slots

NameDescription
label The landmark name and visible title, as one element. Falls back to the site's componentStrings, then "On this page".

Tokens

The global tokens from tokens.json the component reads. Set one in a project's tokens.css to change it everywhere.

Type a value to try it in every example above. Reset puts the default back.

Token Type Default Override
--norn-ui-accentThe brand color, shared by every component. <color> #2346d4
--norn-ui-border-colorHairline color. <color> light-dark(#d3d8e2, #2d323e)
--norn-ui-radius-sCorner radius of a part inside a component, and of inline code. A component's own radius is ui.border.radius. <length> 4px
--norn-ui-focus-offsetGap between an element and its focus ring. An element the ring would clip draws it inset, at the negative of this. <length> 2px
--norn-ui-state-hoverShare of the text color mixed into the background while the pointer is over a control. <percentage> 8%
--norn-ui-state-pressShare of the text color mixed into the background while a control is pressed, and of the accent on a selected or current item. <percentage> 12%
--norn-ui-motion-durationLength of a state change, such as a hover layer. <time> 150ms
--norn-ui-motion-easingEasing for every transition. <easing-function> cubic-bezier(0.2, 0, 0, 1)
--norn-surface-raisedRaised surface. <color> light-dark(hsl(40, 14%, 96%), #242932)
--norn-text-baseText color. <color> light-dark(#16181d, #eceef3)
--norn-text-mutedSecondary text color. <color> light-dark(#4b5160, #a4abba)
--norn-text-accentThe accent for text and links: darkened in light mode, lightened in dark mode. The lightness caps keep any accent at 4.5:1 or better. <color> light-dark(oklch(from color-mix(in oklch, var(--norn-ui-accent, #2346d4) 82%, black) min(l, 0.5) c h), oklch(from color-mix(in oklch, var(--norn-ui-accent, #2346d4) 55%, white) max(l, 0.72) c h))
--norn-font-size-sSmall text: captions, code, navigation, and notes. <length> 0.875rem
--norn-space-2xsSmallest spacing step. <length> 0.25rem
--norn-space-xsExtra small spacing step. <length> 0.5rem
--norn-space-sSmall spacing step. <length> 0.75rem