# Table of Contents **A table of contents that highlights the headings you are reading.** **Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/Toc) ยท [Zag.js Docs](https://zagjs.com/components/react/toc) **TocExamples.html** ```html
{heading.label}

{heading.text}
On this page {heading.label}
``` ## Features - Highlights the links of the headings that are visible, tracked with an `IntersectionObserver` - Highlights several links at once when several headings are visible - Scrolls its own list so the first active link stays in view - Follows the headings of a scroll container as well as of the page - Sets `aria-current="location"` on the active links - Exposes the position of the active links for an animated indicator ## Anatomy ```html ``` ## Installation ```bash typo3 ui:add toc ``` Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Registry/Toc) into your project. Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md). ## Examples ### Build the items from your content `items` takes `TocItem` objects or arrays with a `value` (the id of the heading element) and a `depth`. A `TocItem` also carries the `label` for your template and for client scripts. ```php use Jramke\FluidPrimitives\Domain\Dto\TocItem; $items = array_map( static fn(array $header) => new TocItem(value: 'c' . $header['uid'], depth: 2, label: $header['header']), $contentElements, ); ``` ```html {item.label} ``` ### Indent nested headings List the `depth` of each heading in `items`: `2` for an `h2`, `3` for an `h3`. An item exposes it as the `--depth` CSS variable, which the `ui:toc.item` of the registry turns into an indent. **TocExamples.html** ```html
{heading.label}

{heading.text}
On this page {heading.label}
``` ### Follow the active link with an indicator Place a `ui:toc.indicator` in the list. It follows the active links through the `--top`, `--height`, `--left` and `--width` CSS variables of the root, and the list is its positioning context. **TocExamples.html** ```html
{heading.label}

{heading.text}
On this page {heading.label}
``` ### Draw a rail Each link draws a segment of the rail beside it, and the segment of an active link turns dark. A heading one level deeper steps the rail in, with a curve where the level changes. **TocExamples.html** ```html
{heading.label}

{heading.text}
On this page The rail of a link is drawn from the depth of its neighbours: it bends where the depth changes. The dark copy of the rail is clipped away below the active items (from the bottom) and above them (from the top), so it draws in and out along the direction you scroll. {heading.label}
``` ### Collapse the list into a summary Put the list into a `ui:collapsible`. The trigger shows the active heading and how far you are, so the list can stay closed. The script mounts the `Toc` itself and updates the summary from `onActiveChange`: the `--progress` of the ring, the number and the label of the active heading. **TocExamples.html** ```html
- On this page {heading.label}
{heading.label}

{heading.text}
``` **Collapsible.entry.ts** ```ts import { mount, mountAll } from 'fluid-primitives'; import { Toc } from 'fluid-primitives/toc'; mountAll('ui:tocExamples.collapsible', ({ props, createHydrator }) => { const hydrator = createHydrator(); const ring = hydrator.query('ring'); const number = hydrator.query('number'); const label = hydrator.query('label'); if (!ring || !number || !label) return; mount('ui:toc', `${props.id}-toc`, ({ props }) => { const toc = new Toc({ ...props, onActiveChange: ({ activeIds }) => { const index = toc.api.items.findIndex(item => item.value === activeIds[0]); ring.style.setProperty('--progress', String((index + 1) / toc.api.items.length)); number.textContent = String(index + 1); label.textContent = toc.hydrator.queryAll('link')[index]?.textContent?.trim() ?? ''; }, }); return toc.init(); }); }); ``` ## API Reference ### toc.root Wraps the table of contents, provides its state and takes the `items`. Renders a `