Table of contents (TableOfContents)

All components (204)

Navigation · TableOfContents · .amset-toc

What it is and when to use it

The index of a long page: the sections as a list of links, with the one being read highlighted. When one is pressed, the page scrolls down to it and focus goes with it.

When to use it

Product sheets, terms and conditions, help guides: pages several screens tall with sections that have their id.
indented on a section for a subsection inside another.
hiddenLabel when it is already clear that it is an index and the title gets in the way: it still has its name for the screen reader.
offset with a fixed header: the pixels it covers, so the section does not end up under it when jumping.

When not to

To go to other pages of the application: SideNav or TopBar.
To show one section at a time instead of the whole page: Tabs or Accordion.

Keyboard: Tab goes through the links; Enter takes you to the section and passes focus to it, so the next Tab continues inside it and does not go back to the index. With Control, Cmd, Shift or Alt the click is handled by the browser (open in another tab or window).

Accessibility: it is a nav named by its title ("On this page" by default). They are real links (href="#seccion"): they can be copied, opened in another tab and work without JavaScript, and on pressing, the address is updated without touching the history state, which belongs to the router (with it empty, the application's router loses count when going back). The section being read has aria-current="true" and is marked with the line and the weight in addition to the color. The highlighted one is the last one that has passed the reading line (at 30% of the window height), not the first one that peeks in.

Fine-tuning: CSS variables --amset-toc-*: -font, -font-nested, -indent, -padding-block, -padding-inline. The size changes the font size, the padding and the indentation of the subsections.

What it looks like

<TableOfContents
  label="On this page"
  sections={[
    { key: 'that', label: 'What it is' },
    { key: 'keyboard', label: 'Keyboard', indented: true },
  ]}
/>

Props

Import it with import { TableOfContents } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`sections`required	`readonly AnchorSection[]`	—
`active`	`string`	Controlled: which section is marked. Without this, what is on screen decides.
`className`	`string`	Merged with the library classes; it does not replace them.
`hiddenLabel`	`boolean`	The title for the screen reader only.
`label`	`string`	Title of the index. It is what names the navigation.
`offset`	`number`	How much a fixed header covers at the top, in pixels. On pressing an entry the section stays BELOW the header, not covered by it, and the reading line is counted from its bottom edge. By default, 0.
`onChange`	`(key: string) => void`	—
`size`	`"sm" \| "md" \| "lg"`	The font size and the padding of each entry.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-toc-font`	`var(--amset-text-sm)`
`--amset-toc-font-nested`	`var(--amset-text-xs)`
`--amset-toc-padding-block`	`var(--amset-space-1)`
`--amset-toc-padding-inline`	`var(--amset-space-3)`
`--amset-toc-indent`	`var(--amset-space-6)`

How to change it

.amset-toc {
  --amset-toc-font: ...;
  --amset-toc-font-nested: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: