All experiments

LAB 002 / Navigation systems

Proximity Navigation

A quiet rail for long pages. A slimmer alternative to a table of contents.

01 / The idea

A rail for long pages.

Proximity rail

Live
chapters

Only the main sections. Add waves from the marker settings to see the space between them.

lines
Waves

Fill the space between chapters with smaller marks.

Positionright

Long pages are easy to lose your place in. This rail keeps the document's shape at the edge of the screen without taking up a column.

Choose a mode and marker style above. Then scroll, hover over the rail, or use one of its links.

02 / Orientation

See where you are.

Each mark belongs to a section. The current one grows darker and longer while the page moves underneath it.

The rail shows enough structure to orient you without repeating the whole outline.

03 / Proximity

Move closer.

Move toward the rail and the nearest marks expand. In chapter mode, their names appear too.

Touch users can use the visible marks. Keyboard users can focus each link and read its label.

05 / For everyone

Small marks, full rows.

The marks stay small, but each one fills its row, so the target is the full row height on a 44px track. Tab focuses each chapter. Enter opens it and moves focus to the section.

Reduced motion turns smooth scrolling off. Screen readers announce the current section.

06 / What's next

Pick the right amount of navigation.

Docs minimap maps every paragraph. Turn on Expanded for the full-height wave field. Chapters lists the main sections, and the waves setting fills the space between them when you want more detail. Indicator only shows reading progress.

Lines take waves; dots take an optional rounded container. Position moves the rail to either side of the viewport. This experiment will stay in Labs until I know when it works better than a normal table of contents.

07 / Install

Take it home.

The rail ships as one item. Hand it your chapters and pick a mode; the defaults match this page. Each chapter needs a matching section id on the page: unique ids, focusable sections with scroll margins, window scrolling only.

Keyboard, screen readers, and reduced motion come along.

The rail ships as one item. The snippet below mirrors this page's defaults; change the mode and marker to taste.

One-time registry setup

I'm not in shadcn's index yet, so point your project at my registry once in components.json:

"registries": { "@harv": "https://components.harv.computer/r/{name}.json" }

Install

pnpm dlx shadcn@latest add @harv/proximity-navigation

Use it

<ProximityNavigation
  chapters={[{ id: "idea", label: "The idea" }]}
  mode="chapters"     // minimap | chapters | indicator
  marker="lines"      // lines | dots
  position="right"    // left | right
  waves               // minimap + lines only (Expanded)
/>

Every mark is a real link that fills its row. Indicator mode isn't clickable; it reports progress instead.

Footnotes

  1. Devouring Details by Rauno Freiberg: the first place I saw a rail like this, and the reason this experiment exists.
  2. Making Software, how a screen works: where the expanded docs minimap got its idea: a full-height map of the page you are on.
  3. RareUI's proximity sidebar: encountered midway through the build; a useful reference for how installable this kind of component can be.
  4. shedsgns taste: the model for the Indicator variant: present, non-clickable, only there to show position. also a very great read.

If you enjoyed reading this or found it insightful, feel free to share it with others or send feedback. It helps me keep on researching and writing.

Say hi