Ballmac UI home

Table Of Contents

An 'On this page' list with a scroll spy and a sliding current-section marker. It collects headings itself or takes a list, and scrolls below sticky headers.

Overview

Short introduction to overview. Enough text that the section has real height and scrolling feels natural.

What this covers

Details about what this covers, written as plain paragraphs for the demo.

Who it is for

Details about who it is for, written as plain paragraphs for the demo.

More detail follows here so the next heading is not in view yet.

Installation

Short introduction to installation. Enough text that the section has real height and scrolling feels natural.

Requirements

Details about requirements, written as plain paragraphs for the demo.

Add the package

Details about add the package, written as plain paragraphs for the demo.

More detail follows here so the next heading is not in view yet.

Usage

Short introduction to usage. Enough text that the section has real height and scrolling feels natural.

Basic example

Details about basic example, written as plain paragraphs for the demo.

Options

Details about options, written as plain paragraphs for the demo.

More detail follows here so the next heading is not in view yet.

Accessibility

Short introduction to accessibility. Enough text that the section has real height and scrolling feels natural.

More detail follows here so the next heading is not in view yet.

Installation

$ pnpm dlx shadcn@latest add @ballmac/table-of-contents

Usage

import { TableOfContents } from "@/components/ballmac/table-of-contents"

The full example is in the Code tab above.

Examples

Explicit items

API reference

PropTypeDefault
items

Links to show. Leave out to collect headings from the page automatically.

TocItem[]—
headingsFrom

Where to look for headings when `items` is not given. Defaults to `<main>`, then the whole page.

React.RefObject<HTMLElement | null>—
levels

Heading levels to collect automatically.

number[][2, 3]
title

Title above the list. Also the accessible name of the navigation.

string—
offset

Pixels reserved at the top for a sticky header; also where a section counts as "reached".

number96
container

A scrollable element to watch and scroll instead of the page.

ScrollContainer—
onNavigate

Called when the reader chooses a link.

(id: string) => void—

Also accepts the standard attributes of its root element.

Accessibility

KeyAction
EnterScrolls to the section and updates the URL hash
Screen readersA labelled navigation; the current section has aria-current=location
Reduced motionJumps instead of smooth scrolling; the marker does not glide

Quality scorecard

7/7

Every applicable check passes

Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.0.0, across 2 examples.

How we measure
  • Passed: Accessibility scan

    No serious or critical issues in light and dark, on a phone and a desktop (axe-core 4.13.0, WCAG 2.1 AA and best-practice rules).

  • Passed: Small screens

    No sideways scrolling at 360, 390 or 1280 px wide.

  • Passed: Reduced motion

    No endless animation to begin with.

  • Passed: Right to left

    Mirrors correctly in Arabic, Hebrew, Persian and Urdu layouts (0% of elements off the mirror, limit 15%).

  • Passed: Clean console

    No console errors or React hydration errors while loading.

  • Passed: Keyboard

    16 tab stops, each showing a visible change when it takes focus. 3 documented keys.

  • Not applicable: Loading, empty and error

    Does not show data or take submissions.

  • Passed: Automated tests

    Covered by table-of-contents.test.tsx.

  • For information: Footprint

    2.1 KB of source (gzip) in 1 file. Installs motion.

Automated checks find a subset of problems and do not replace testing with a screen reader and a keyboard in your own app. What they miss.

Use with AI

Leave items out to collect h2 and h3 headings (they need text; missing ids are created). Current section gets aria-current=location. With the shadcn MCP server set up (guide), ask your agent:

Add the Ballmac UI Table Of Contents (@ballmac/table-of-contents) to this project with the shadcn MCP, then use it where it fits.

Use it for

  • Documentation and long articles
  • Settings pages with many sections

Not for

  • Horizontal in-page tabs; use section-tabs
  • App navigation; use sidebar

Registry JSON: https://ui.ballmac.com/r/table-of-contents.json

Credits

Free to use in personal and commercial projects.

Ballmac UI Pro

Need the whole screen, not one piece?

311 premium blocks (dashboards, settings, calendars, mail, shops, onboarding), a private shadcn registry and Figma tokens. Blocks that show data come with loading, empty and error states built in.

Not ready? Try three Pro blocks free

Leave your email and the blocks appear right here, ready to copy. Yours to use in any project.