Chapter scrubber

A rail of marks, one per chapter, that swell under the pointer like the macOS Dock. The tallest mark, the crest, previews its chapter, so people can jump around a long piece without a table of contents.

Features

• Marks swell in a wave around the pointer or keyboard focus, and the crest previews its chapter as a card, a label, or nothing.
• Runs vertically in a gutter or horizontally along a player, with ticks or dots in three densities.
• Works controlled or uncontrolled, so the marker can follow scroll or playback.
• Respects reduced motion: the springs switch off, and the wave keeps its shape but appears and follows instantly.

Installation

It installs motion with it, for the springs.

Usage

import { ChapterScrubber } from "@/components/ui/chapter-scrubber"
 
const chapters = [
  { id: "intro", title: "Introduction" },
  { id: "tokens", title: "Token tiers", description: "Ramps, then roles." },
  { id: "figma", title: "Figma variables", meta: "12:40" },
]
 
export function Contents() {
  return <ChapterScrubber chapters={chapters} />
}

Chapters sit on the rail in array order, one mark each. The title and description name each mark for screen readers.

Each chapter takes:

type Chapter = {
  id: string
  title: string
  description?: React.ReactNode // clamped to three lines
  meta?: React.ReactNode // a small label beside the title, such as a timestamp
}

Anatomy

Every part the component renders, with the data-slot it carries. You pass chapters; the component builds the rest.

Guidelines

• 01Use it for content with a real sequence: a talk, a long read, a case study, a recording.
• 02Keep between six and thirty chapters. Fewer reads as a list; more stops the wave from reaching the neighbours.
• 03Pick card when chapters have descriptions, label when the title says enough, and none when the page already names the section.
• 04Leave side unset in most layouts. It prefers right or top and flips on its own near the viewport edge.
• 05Set currentIndex from your scroll or playback position so the marker keeps up with the reader between clicks.

Examples

Horizontal

A rail along the top of a player or a slide deck. Ticks stand up from the baseline and the preview opens above.

Dots

variant="dot" swaps ticks for dots, for a softer rail that sits well beside imagery.

Centred ticks

align="center" grows ticks out from the middle line, which balances a rail placed on its own.

Sizes

size sets the density: sm, default and lg. rowSize, restLength and peakLength override it when you need an exact rhythm.

Controlled

Buttons elsewhere on the page drive the same marker the rail sets, through currentIndex and onCurrentIndexChange.

In an article

The rail in a sticky column beside a long read.

Do's and don'ts

API reference

Any other prop goes to the root div.

Data attributes

Style parts by slot or state, for example with [&_[data-slot=chapter-scrubber-preview]]:shadow-none.

Accessibility

• 01The rail is a listbox and every mark an option named by its title and description. The current chapter is aria-selected.
• 02Only one mark is in the tab order. Arrow keys, Home and End move along the rail; Enter or Space makes a chapter current.
• 03Focus raises the wave exactly as hover does, so keyboard users get the same preview.

Related components

• Integration visualA hub and the tools wired into it, with pulses along the routes.
• Token flowWalks a colour token from raw value to primitive to semantic role.
• ReactionsLets people respond to content with an emoji in one tap.

References

• The macOS Dock, whose magnification the wave borrows
• WAI-ARIA listbox pattern, for the keyboard model
• Motion, for the springs