# Floating TOC

A table of contents for an article, with a marker that follows the section in view. It does not stick by itself: put it in a `sticky` container to keep it on screen.

- Category: Core Elements
- Page: https://wunderui.com/components/floating-toc
- Tier: Free

## Install

```bash
npx wunderui-cli add floating-toc
```

## Import

```tsx
import { FloatingToc } from "@/components/wunderui/floating-toc"
```

## Minimal usage

Then use it:

```tsx
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.

## Usage

```tsx
import { useRef } from "react"
import { FloatingToc } from "@/components/ui/floating-toc"

type Section = { id: string; label: string; depth?: number; body: string }

const sections: Section[] = [
  {
    id: "why",
    label: "Why tokens",
    body: "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.",
  },
  {
    id: "setup",
    label: "Set up the theme",
    body: "Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.",
  },
  {
    id: "dark",
    label: "Dark mode",
    depth: 1,
    body: "Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.",
  },
  {
    id: "brand",
    label: "Brand colors",
    depth: 1,
    body: "Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.",
  },
  {
    id: "ship",
    label: "Ship it",
    body: "Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.",
  },
]

export function Example() {
  const articleRef = useRef<HTMLDivElement>(null)

  return (
    <div className="@container">
      <div className="flex flex-col-reverse gap-4 @md:flex-row @md:gap-6">
        <div
          ref={articleRef}
          tabIndex={0}
          aria-label="Theming WunderUI"
          className="h-72 min-w-0 flex-1 overflow-y-auto rounded-xl border border-border bg-card px-5 py-4 focus-ring"
        >
          <p className="mb-3 text-lg font-semibold text-foreground">Theming WunderUI</p>
          {sections.map((section) => (
          <section key={section.id} id={section.id} className="scroll-mt-2 pb-6">
            <p className={section.depth ? "mb-1.5 text-sm font-medium text-foreground" : "mb-1.5 text-base font-semibold text-foreground"}>
              {section.label}
            </p>
            <p className="text-sm leading-6 text-text-secondary">{section.body}</p>
          </section>
          ))}
          <div aria-hidden className="h-36" />
        </div>
        <div className="shrink-0 @md:w-44">
          <p className="mb-2 text-xs font-medium text-text-tertiary uppercase">On this page</p>
          <FloatingToc
            items={sections.map(({ id, label, depth }) => ({ id, label, depth }))}
            scrollContainer={articleRef}
          />
        </div>
      </div>
    </div>
  )
}
```

## 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

- [Tabs](https://wunderui.com/components/tabs) for peer views that people switch between, one at a time
- [Breadcrumb](https://wunderui.com/components/breadcrumb) for the path to the current page in a site
- [Stepper](https://wunderui.com/components/stepper) for the steps of a flow with a fixed order

## Keyboard

The entries are plain links, so the browser handles focus and activation. The article's scroll container is focusable too.

| Key | Action |
|---|---|
| `Tab` or `Shift+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 `onSelect` is called. Space does not activate a link. |
| `↑` or `↓` | With focus in the scroll container of the article (give it `tabIndex={0}`), scrolls the article. The marker follows the section in view. |

## Behavior

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

- `FloatingToc`: A nav named On this page with one link per section. It is not sticky itself, so place it in a sticky column.
- `Entry`: 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.
- `Active marker`: 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

### When to use

- Use a Floating TOC beside a long page with several headed sections, such as documentation or a policy. For switching between separate views, use Tabs.

### 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.
- 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.
- Put it in a sticky column yourself. The component draws the list and the marker, not its position.
- 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 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

| Prop | Type | Default | Description |
|---|---|---|---|
| items* | TocItem[] |  | The entries, in page order. `id` is the id of the section it points to, `label` is the text and `depth` indents it, 12 px per level. |
| activeId | string |  | The id of the current entry, for a contents you track yourself. Setting it turns the scroll spy off. |
| className | string |  | Extra classes for the `<nav>`, merged with its own. Use it for the width or the spacing around the list. |
| onSelect | (id: string) => void |  | Called with the id of the entry that was clicked, after the marker has moved. |
| scrollContainer | React.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. |

## Examples

### Depth: flat, nested and deep entries

```tsx
import { useRef } from "react"
import { FloatingToc } from "@/components/ui/floating-toc"

type Section = { id: string; label: string; depth?: number; body: string }

const sections: Section[] = [
  {
    id: "why",
    label: "Why tokens",
    body: "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.",
  },
  {
    id: "setup",
    label: "Set up the theme",
    body: "Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.",
  },
  {
    id: "dark",
    label: "Dark mode",
    depth: 1,
    body: "Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.",
  },
  {
    id: "brand",
    label: "Brand colors",
    depth: 1,
    body: "Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.",
  },
  {
    id: "ship",
    label: "Ship it",
    body: "Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.",
  },
]

export function Example() {
  const articleRef = useRef<HTMLDivElement>(null)

  return (
    <div className="@container">
      <div className="flex flex-col-reverse gap-4 @md:flex-row @md:gap-6">
        <div
          ref={articleRef}
          tabIndex={0}
          aria-label="Theming WunderUI"
          className="h-72 min-w-0 flex-1 overflow-y-auto rounded-xl border border-border bg-card px-5 py-4 focus-ring"
        >
          <p className="mb-3 text-lg font-semibold text-foreground">Theming WunderUI</p>
          {sections.map((section) => (
          <section key={section.id} id={section.id} className="scroll-mt-2 pb-6">
            <p className={section.depth ? "mb-1.5 text-sm font-medium text-foreground" : "mb-1.5 text-base font-semibold text-foreground"}>
              {section.label}
            </p>
            <p className="text-sm leading-6 text-text-secondary">{section.body}</p>
          </section>
          ))}
          <div aria-hidden className="h-36" />
        </div>
        <div className="shrink-0 @md:w-44">
          <p className="mb-2 text-xs font-medium text-text-tertiary uppercase">On this page</p>
          <FloatingToc
            items={sections.map(({ id, label, depth }) => ({ id, label, depth }))}
            scrollContainer={articleRef}
          />
        </div>
      </div>
    </div>
  )
}
```

### Placement: sticky column or inline

```tsx
import { useRef } from "react"
import { FloatingToc } from "@/components/ui/floating-toc"

type Section = { id: string; label: string; depth?: number; body: string }

const sections: Section[] = [
  {
    id: "why",
    label: "Why tokens",
    body: "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.",
  },
  {
    id: "setup",
    label: "Set up the theme",
    body: "Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.",
  },
  {
    id: "dark",
    label: "Dark mode",
    depth: 1,
    body: "Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.",
  },
  {
    id: "brand",
    label: "Brand colors",
    depth: 1,
    body: "Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.",
  },
  {
    id: "ship",
    label: "Ship it",
    body: "Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.",
  },
]

export function Example() {
  const boxRef = useRef<HTMLDivElement>(null)

  return (
    <div
      ref={boxRef}
      tabIndex={0}
      aria-label="Theming WunderUI"
      className="@container h-80 overflow-y-auto rounded-xl border border-border bg-card focus-ring"
    >
      <div className="flex flex-col-reverse gap-4 px-5 py-4 @md:flex-row @md:gap-6">
        <div className="min-w-0 flex-1">
          <p className="mb-3 text-lg font-semibold text-foreground">Theming WunderUI</p>
          {sections.map((section) => (
          <section key={section.id} id={section.id} className="scroll-mt-2 pb-6">
            <p className={section.depth ? "mb-1.5 text-sm font-medium text-foreground" : "mb-1.5 text-base font-semibold text-foreground"}>
              {section.label}
            </p>
            <p className="text-sm leading-6 text-text-secondary">{section.body}</p>
          </section>
          ))}
          <div aria-hidden className="h-40" />
        </div>
        <aside className="shrink-0 @md:sticky @md:top-4 @md:w-44 @md:self-start">
          <p className="mb-2 text-xs font-medium text-text-tertiary uppercase">On this page</p>
          <FloatingToc items={sections.map(({ id, label, depth }) => ({ id, label, depth }))} scrollContainer={boxRef} />
        </aside>
      </div>
    </div>
  )
}
```

### States: the current entry

```tsx
import { FloatingToc } from "@/components/ui/floating-toc"

const items = [
  { id: "introduction", label: "Introduction" },
  { id: "installation", label: "Installation" },
  { id: "usage", label: "Usage" },
  { id: "api-reference", label: "API Reference" },
]

export function Example() {
  return <FloatingToc items={items} activeId="usage" className="w-44" />
}
```

## In context

### Documentation page: contents in a sticky column

The guide scrolls under a fixed title bar and the contents stay in view beside it. Scroll the guide, or click an entry, and the marker follows and the guide scrolls to the section.

```tsx
import { useRef } from "react"
import { FloatingToc } from "@/components/ui/floating-toc"

type Section = { id: string; label: string; depth?: number; body: string }

const sections: Section[] = [
  {
    id: "why",
    label: "Why tokens",
    body: "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.",
  },
  {
    id: "setup",
    label: "Set up the theme",
    body: "Import the stylesheet once at the root of your app. The tokens live on :root, so any element can read them without a provider.",
  },
  {
    id: "dark",
    label: "Dark mode",
    depth: 1,
    body: "Dark values sit under the .dark class. Toggle it on the html element and the whole interface switches, including charts and focus rings.",
  },
  {
    id: "brand",
    label: "Brand colors",
    depth: 1,
    body: "Override --primary and its foreground to rebrand. Tints and hovers are mixed from it, so they stay in tune.",
  },
  {
    id: "ship",
    label: "Ship it",
    body: "Tokens compile to plain CSS custom properties. Nothing runs at build time, and nothing extra ships to the browser.",
  },
]

export function Example() {
  const guideRef = useRef<HTMLDivElement>(null)

  return (
    <div className="overflow-hidden rounded-xl border border-border bg-card">
      <div className="border-b border-border px-5 py-3">
        <p className="text-xs text-text-tertiary">Guides</p>
        <p className="text-base font-semibold text-foreground">Theming</p>
      </div>
      <div ref={guideRef} tabIndex={0} aria-label="Theming WunderUI" className="@container h-80 overflow-y-auto focus-ring">
        <div className="flex flex-col-reverse gap-4 px-5 py-4 @md:flex-row @md:gap-6">
          <div className="min-w-0 flex-1">
            {sections.map((section) => (
            <section key={section.id} id={section.id} className="scroll-mt-2 pb-6">
              <p className={section.depth ? "mb-1.5 text-sm font-medium text-foreground" : "mb-1.5 text-base font-semibold text-foreground"}>
                {section.label}
              </p>
              <p className="text-sm leading-6 text-text-secondary">{section.body}</p>
            </section>
            ))}
            <div aria-hidden className="h-40" />
          </div>
          <aside className="shrink-0 @md:sticky @md:top-4 @md:w-44 @md:self-start">
            <p className="mb-2 text-xs font-medium text-text-tertiary uppercase">On this page</p>
            <FloatingToc items={sections.map(({ id, label, depth }) => ({ id, label, depth }))} scrollContainer={guideRef} />
          </aside>
        </div>
      </div>
    </div>
  )
}
```

### Policy page: contents above the text

On a narrow page the contents sit above the text instead of beside it, and scroll away with it. The marker still follows the section being read.

```tsx
import { useRef } from "react"
import { FloatingToc } from "@/components/ui/floating-toc"

const sections = [
  {
    id: "collect",
    label: "What we collect",
    body: "Your name, your email address and the workspace you create. We also log which pages you open, so we can fix what breaks.",
  },
  {
    id: "use",
    label: "How we use it",
    body: "To run your account, to send receipts and product updates you asked for, and to understand which features people use.",
  },
  {
    id: "share",
    label: "Who sees it",
    body: "Only the people in your workspace and the processors that host and bill it for us. We never sell personal data.",
  },
  {
    id: "keep",
    label: "How long we keep it",
    body: "For as long as your account is open, and for 30 days after you close it, so you can still export your work.",
  },
  {
    id: "choices",
    label: "Your choices",
    body: "You can export or delete your data at any time in Settings, and turn off product updates in one click.",
  },
  {
    id: "contact",
    label: "Contact",
    body: "Write to info@wunderui.com for any question about this policy. We answer within two working days.",
  },
]

export function Example() {
  const pageRef = useRef<HTMLDivElement>(null)

  return (
    <div
      ref={pageRef}
      tabIndex={0}
      aria-label="Privacy policy"
      className="h-80 overflow-y-auto rounded-xl border border-border bg-card px-5 py-4 focus-ring"
    >
      <p className="text-lg font-semibold text-foreground">Privacy policy</p>
      <p className="mt-1 mb-4 text-sm text-text-secondary">Last updated 9 November 2026</p>
      <FloatingToc items={sections.map(({ id, label }) => ({ id, label }))} scrollContainer={pageRef} className="mb-6" />
      {sections.map((section) => (
      <section key={section.id} id={section.id} className="scroll-mt-2 pb-6">
        <p className="mb-1.5 text-base font-semibold text-foreground">{section.label}</p>
        <p className="text-sm leading-6 text-text-secondary">{section.body}</p>
      </section>
      ))}
      <div aria-hidden className="h-40" />
    </div>
  )
}
```

## For AI agents

`get_component("floating-toc")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
