Floating TOC
FreeList the sections of a long page, with a marker that follows the section the reader is in.
npx wunderui-cli add floating-tocPlayground
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
On this page
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
On this page
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
On this page
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
On this page
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Toggle the class
Add or remove the dark class when the choice changes, and keep it in local storage so it survives a reload.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
On this page
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Toggle the class
Add or remove the dark class when the choice changes, and keep it in local storage so it survives a reload.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
On this page
Installation
npx wunderui-cli add floating-tocWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { FloatingToc } from "@/components/wunderui/floating-toc"Then use it:
import { useRef } from "react"
import { FloatingToc } from "@/components/ui/floating-toc"
export function Guide() {
const articleRef = useRef<HTMLDivElement>(null)
return (
<div className="flex gap-6">
<div ref={articleRef} className="h-72 flex-1 overflow-y-auto">
<section id="why">Every color is a token.</section>
<section id="setup">Import the stylesheet once.</section>
</div>
<FloatingToc
items={[
{ id: "why", label: "Why tokens" },
{ id: "setup", label: "Set up the theme" },
]}
scrollContainer={articleRef}
/>
</div>
)
}Expected result: You see a scrolling article with two sections and two links beside it. The marker sits on the section being read and moves as you scroll or click.
When to use
Use Floating TOC for
- Documentation and guides with several headed sections
- Policies, terms and release notes that people scan for one part
- Long single pages where the reader needs to see where they are
Use something else for
- Tabs for peer views that people switch between, one at a time
- Breadcrumb for the path to the current page in a site
- Stepper for the steps of a flow with a fixed order
Depth
Give an item a depth to indent a sub-section under its parent, 12 px per level. Keep it to two or three levels, because deeper entries get hard to read.
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
On this page
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
On this page
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Toggle the class
Add or remove the dark class when the choice changes, and keep it in local storage so it survives a reload.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
On this page
Placement
The component is not sticky itself. Put it in a sticky column beside the article, or inline above it on a narrow layout.
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
Theming WunderUI
Why tokens
Every color, radius and shadow in WunderUI is a token. Change one value and every component that uses it follows, in light and in dark.
Set up the theme
Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.
Dark mode
Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.
Brand colors
Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.
Ship it
Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.
States
One entry is current: darker, medium weight and carrying the marker. Hover and focus preview the marker on another entry, and you can set the current entry yourself.
Keyboard interactions
The entries are plain links, so the browser handles focus and activation. The article's scroll container is focusable too.
- TaborShift+Tab
- Moves focus to the next or previous entry. The focused entry previews the marker, as hover does.
- Enter
- Follows the focused link: the section scrolls into view, the marker moves to the entry at once and is called. Space does not activate a link.
- ↑or↓
- With focus in the scroll container of the article (give it ), scrolls the article. The marker follows the section in view.
Behavior and motion
How the contents react to scrolling, clicks and motion.
- Scroll spy
- The current section is the last one that has scrolled past a line a quarter of the way down. At the end of the scroll, the last section wins, even a short one.
- Click
- A click scrolls the section into view and moves the marker at once. The marker stays put until the scroll ends, so it doesn't flicker through the sections in between.
- Scroll container
- By default the spy watches the window and a click updates the address bar hash. Pass a scroll container to watch that element instead, and the address bar stays unchanged.
- Controlled
- Set the active id yourself and the spy turns off: the marker only moves when you change it. A click still scrolls and calls the select handler, so update the id there.
- Missing ids
- An item whose section isn't on the page is listed but never becomes current. Clicking it follows the plain link.
- Hover and focus
- The entry under the pointer or focus gets a fainter preview marker, showing where a click would go. It disappears on leave and blur.
- Depth
- Depth indents an entry by 12 px per level. Nothing else changes: no collapsing, no limit.
- Marker motion
- The marker glides between entries at the base duration and the preview marker moves faster. Text colour changes quickly.
- Reduced motion
- With reduced motion the marker jumps to the new entry and a click scrolls at once instead of smoothly. Colour changes stay.
Anatomy
The parts of the contents, numbered in the figure. They are plain elements.
- 1
A nav named On this page with one link per section. It is not sticky itself, so place it in a sticky column.
- 2
A link to each section's id, indented 12 px per depth. The current one is darker and medium weight, and is marked as the current location.
- 3Optional
A 2 px bar on the left line that glides to the current entry. A fainter one previews the entry under the pointer or focus.
Best practices
- Do
Give every section an id that matches its item. The links and the scroll spy find sections by that id, and a missing one is never marked.
- Do
Pass the scroll container when the sections scroll inside a panel rather than the page. Otherwise the spy watches the window and the marker stands still.
- Do
Put it in a sticky column yourself. The component draws the list and the marker, not its position.
- Do
Keep labels short, one line each, and in page order. A wrapped entry throws the marker out of line.
- Don’t
Leave the active section unset unless you track it yourself. Once you set it, the scroll spy is off and the marker stops following the reader.
- Don’t
Don't use it as the main navigation of a site. It lists the sections of one page and shows where the reader is.
API reference
FloatingToc draws one list and takes the props below. Each item has an id, a label and an optional depth.
A nav named On this page with one link per section. It is not sticky itself, so place it in a sticky column.
| Prop | Type | Default | Description |
|---|---|---|---|
| items required | TocItem[] | — | The entries, in page order. is the id of the section it points to, is the text and indents it, 12 px per level. |
| scrollContainer | RefObject<HTMLElement | null> | — | A ref to the element that scrolls the sections, when it is not the page. The spy and a click then work inside it. |
| activeId | string | — | The id of the current entry, for a contents you track yourself. Setting it turns the scroll spy off. |
| onSelect | (id) => void | — | Called with the id of the entry that was clicked, after the marker has moved. |
| className | string | — | Extra classes for the , merged with its own. Use it for the width or the spacing around the list. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("floating-toc")npx wunderui-cli add floating-tocThe full library index for assistants is at /llms.txt.