Components•Minimap scrollbar

Minimap scrollbar

A scroll rail that shows where you are in the document and how it is built. Ticks mark headings and blocks, and the heading under your pointer appears in a label.

Dependencies

Motion clsx

Copy below cli

npx shadcn@latest add @bjork-ui/minimap-scrollbar

How to use

import { useRef } from "react";import { MinimapScrollbar } from "@/components/bjork-ui/navigation/minimap-scrollbar";export function Article() {  const scrollRef = useRef<HTMLDivElement>(null);  return (    <div className="relative h-[440px]">      <div ref={scrollRef} className="h-full overflow-y-auto">        {/* headings and paragraphs */}      </div>      <MinimapScrollbar target={scrollRef} />    </div>  );}

Notes on optical alignment

Measured centres and visual centres rarely agree. These notes collect the habits that close the gap, from small icons to long columns of figures.

Starting from the eye

A box can be perfectly centred and still look low. Filled shapes carry more weight than outlines, and flat edges read heavier than curves of the same size.

Start with the bounding box, then step back and judge the weight. Move in small steps and stop when the shape stops feeling off.

Centring small shapes

Small glyphs need the most attention because a pixel is a large share of their size.

Icon centring

Triangles and arrows should sit slightly toward the direction they point. Their centroid is what the eye reads, not the corners of their box.

Round icons can overshoot the box a little so they match the square ones next to them.

Padding and balance

Equal padding on every side often looks uneven. A label with a leading icon usually needs less space on the icon side.

Padding asymmetry

Trim the side that already carries an icon by a couple of pixels. Leave the text side alone so the words keep their rhythm.

Check the result with the blur test. The visual mass should land where the box centre is.

Shape weight and punctuation

Counters, the open space inside letters, change how heavy a word looks. Tight counters darken a line, open ones lighten it.

Hanging punctuation lets quotes and bullets sit outside the text edge, so the first letters line up down the column.

Type at small and large sizes

A single typeface can behave differently across sizes. Display cuts run tighter with finer joins, while text cuts open up for legibility.

Optical sizes

Pick the cut that matches the size on screen. A large heading set in a text cut looks loose and underweight.

Keep optical sizing automatic where the font supports it, and only override it when a layout demands a fixed look.

Figures in columns

Numbers that change, such as counters and timers, should keep a fixed width so the layout does not wobble on every tick.

Tabular numerals

Set columns of figures with tabular numerals so the digits share one advance width and line up by their place value.

Proportional figures look nicer in running prose. Switch to tabular only where digits stack.