Skip to main content
xtylext xtyle
xriptxr

Toc
Info:Navigation
26

An on-this-page table of contents that highlights the section currently in view.
table of contents on this page outline anchor nav jump links

Live demo

live · @xtyle/astro

Toc

Introduction

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Anchors

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Named hues

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Ramps

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Knobs

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Accent strategy

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Coverage

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Scroll this column and watch the active link track the heading in view. Every entry is a real anchor, so it jumps on click and works with no script at all.

Toc lists the sections of a page as in-page links and tracks which one the reader is looking at. Give it items: each is an id matching a section's element id, a label, and an optional 1-based level, and it renders a labelled nav of anchor links.

Entries deeper than the one before them nest inside it as a real sublist, so a two-level outline is structural rather than an indent an assistive reader can't see; a level that skips a depth is treated as one step down, which is what heading sources actually emit. An IntersectionObserver then marks the active link as you scroll, setting aria-current and the accent rail. The links work as plain anchor jumps with no script, and a clicked section still lights its entry without one, so the scrollspy is pure progressive enhancement. It reads as a vertical rail beside the content and folds into a wrapped row of chips on narrow screens. Pass sticky to keep it in view as the page scrolls.

When to use

How this component composes with the rest of the set.

Place it in a sidebar column beside the content; pass sticky so it follows the scroll.
Point each item.id at a section's element id so the in-page anchor and the scrollspy target line up.
Pair with Heading sections that carry matching ids; the Toc is the map, the headings are the territory.

Props

3 props, straight from the manifest.

PropTypeDefaultBindingsDescription
items TocItem[] —
html svelte astro
The sections, each `{ id, label, level? }`; `id` matches the target element's id, `label` is the link text, and `level` is the 1-based outline depth (default 1) that decides nesting. On the custom element, a JSON string.
label string On this page
html svelte astro
The heading above the list.
sticky boolean false
html svelte astro
Pins the nav with `position: sticky` so it stays in view while the page scrolls.

Appearance

States

active

 .xtyle-toc__link.is-active

The link for the section currently in view: accent ink and rail, set alongside aria-current.

focus-visible

 .xtyle-toc__link:focus-visible

Keyboard focus on a link: a token ring plus a transparent outline that becomes real in forced-colors mode.

Anatomy

The named parts that make up the component, with their selectors.

toc

 .xtyle-toc

The nav root carrying the rail border and (optional) sticky positioning.
--space-3 --space-2 --space-5 --border-thin --line --radius-md --bg-1

label

 .xtyle-toc__label

The small uppercase heading above the list.
--font-sans --text-xs --weight-semibold --fg-2 --space-2

nested list

 .xtyle-toc__list--nested

A sublist of deeper entries, nested inside the li of the section it belongs to.
--space-4 --fg-3 --text-xs

link

 .xtyle-toc__link

A section link with its accent rail when active and a focus ring.
--font-sans --text-sm --fg-2 --fg-0 --border-thick --accent-text --accent --weight-medium --duration-fast --ease-standard --border-normal --ring --radius-sm --accent-bg

Tokens & coverage

What the component consumes, checked live against what the algorithm produces.

Success:fully covered 26/26 consumed tokens produced default register: 305 tokens

Live coverage check against the xtyle-default register (derive(xtyleDefault, { anchors }) → coverComponent(manifest, register)). Every token this component consumes must be a key the algorithm produces.

--accent --accent-bg --accent-text --bg-1 --border-normal --border-thick --border-thin --duration-fast --ease-standard --fg-0 --fg-2 --fg-3 --font-sans --line --radius-md --radius-sm --ring --space-1 --space-2 --space-3 --space-4 --space-5 --text-sm --text-xs --weight-medium --weight-semibold

Accessibility
The nav names itself (aria-label) and the active link carries aria-current, so assistive tech announces which section is in view.
level nests the list markup rather than indenting it, so a screen reader reports a subsection as a child of its section instead of a sibling.
Every entry is a real in-page anchor link, so the table of contents works fully without JavaScript; the scrollspy only decorates it.
With no script, the clicked section still highlights its own entry: a generated :target rule stands in for the scrollspy, and stands down as soon as the observer takes over.
Links show keyboard focus with a focus-visible ring plus a transparent outline the forced-colors base rule promotes to a real system outline.

Code

A scrollspy table of contents

A sticky rail of section links that tracks the section in view; entries carrying a deeper level nest under the one above them, and on narrow screens the whole thing folds into a wrapped row.

 
<xtyle-toc
	label="On this page"
	sticky
	items='[{"id":"intro","label":"Intro"},{"id":"usage","label":"Usage"},{"id":"options","label":"Options","level":2},{"id":"api","label":"API"}]'
></xtyle-toc>
 
<script lang="ts">
	import { Toc } from "@xtyle/svelte";

	const items = [
		{ id: "intro", label: "Intro" },
		{ id: "usage", label: "Usage" },
		{ id: "options", label: "Options", level: 2 },
		{ id: "api", label: "API" },
	];
</script>

<Toc {items} label="On this page" sticky />
 
---
import { Toc } from "@xtyle/astro";

// getHeadings() returns { depth, slug, text } per heading, which maps straight across
const items = Astro.props.headings.map((h) => ({ id: h.slug, label: h.text, level: h.depth - 1 }));
---

<Toc items={items} label="On this page" sticky />