Toc

import { Toc } from '@contour-ui/react';

const items = [
  { value: 'install', depth: 2 },
  { value: 'usage', depth: 2 },
  { value: 'props', depth: 3 },
];

<Toc.Root items={items}>
  <Toc.Title>On this page</Toc.Title>
  <Toc.Indicator />
  <Toc.List>
    {items.map((item) => (
      <Toc.Item key={item.value} item={item}>
        <Toc.Link>{titles[item.value]}</Toc.Link>
      </Toc.Item>
    ))}
  </Toc.List>
</Toc.Root>;

Toc lists the headings of a page by id (value) and level (depth), and watches them as the page scrolls. The links of the headings in the upper part of the view, from 20px below its top down to 60% of its height, are active: they take the default text color, and the indicator spans them. When no heading is there, the last one scrolled past stays active, since its section fills the view. A click on a link scrolls to the heading and puts its id in the address. Scroll the manual above, or click its contents.

Toc is the Headless Toc with the look of contour-ui: the behavior and every prop are described there.

With Fumadocs

A Fumadocs page has its table of contents as toc: items { title, url: '#id', depth }. Its id is the url without the #:

import { Toc } from '@contour-ui/react';
import type { TableOfContents } from 'fumadocs-core/toc';

export function TocPanel({ toc }: { toc: TableOfContents }) {
  const items = toc.map(({ url, depth }) => ({ value: url.slice(1), depth }));
  return (
    <Toc.Root items={items}>
      <Toc.Title>On this page</Toc.Title>
      <Toc.Indicator />
      <Toc.List>
        {toc.map(({ title, url, depth }) => (
          <Toc.Item key={url} item={{ value: url.slice(1), depth }}>
            <Toc.Link>{title}</Toc.Link>
          </Toc.Item>
        ))}
      </Toc.List>
    </Toc.Root>
  );
}

A new array with the same items, as map makes on every render, is fine: Toc watches the headings again only when the items change.

Scroll containers

By default the headings scroll with the page. When they scroll in an element of their own, as in the example above, return it from scrollEl:

<Toc.Root items={items} scrollEl={() => document.getElementById('manual')}>
  …
</Toc.Root>

A long table of contents often sits in a panel that scrolls on its own, such as a sticky column. As the active links change, Toc scrolls that panel to keep the first one in view, and never the page. A list that shows later, as in a popover that opens, shows with that link in view. autoScroll={false} turns this off.

Anatomy

The list draws a line along its start, and the indicator, an accent bar, runs over it: the root places it from --top and --height, the box around the active items, and it slides there when they change. It is hidden while no item is active or the list is hidden, and a list that shows, as in a popover, shows it in place, without the slide. Each level below depth 2 (an h2) indents an item one step, down to 6.

data-active is present, and empty, on the item and the link of every active heading; aria-current="true" marks the link of the first one.

Props

Toc.Root:

Toc.Item takes the item of its heading, { value, depth }. Every part takes asChild and the props of its element, such as className, style and id; className is merged with the part's class. More on each prop: Headless Toc.

Keyboard

The links are links: these are the browser's own keys.

Accessibility

• A named landmark. Toc.Root is a nav, named by Toc.Title while one is mounted. Without a title, name it with aria-label: a page with several navigations needs a name for each.
• The current section. The link of the first active heading has aria-current="true", which screen readers announce as "current". The other active links are marked for the eyes, by the color and the indicator, not by color alone.
• Focus follows the link. A click on a link moves focus to the heading, as following a link to it does, so screen readers read on from there and the next Tab starts there.
• Reduced motion. When the user prefers reduced motion, a click jumps to the heading instead of scrolling smoothly, and the indicator moves without sliding.

Tokens