--- title: Reading description: A family of primitives for long-form content pages — progress, spine, minimap, bookmark, meta, plus a one-tag composition shell visibility: guest draft: false --- # Reading The reading-* family — a set of complementary primitives for long-form content pages. A blog post, a docs page, a long-form article: the family covers "where am I in the article", "navigate the structure", "see the density at a glance", "resume where I left off", "how long is this", and a one-tag composition wrapper. ::: warning Viewport-scoped layout The `reading-*` family of primitives defaults to `position: fixed` relative to the viewport — they're designed for full-page reading experiences (article pages, docs sites). **Avoid** nesting one inside a normal-width card, grid, or dashboard tile **without** the `boundary` prop: the fixed element ignores its parent's intrinsic width, producing double scrollbars and visual overflow. Pin them at the page level (inside `
` or `
`), never inside a constrained container. ::: ## Quick start (the "I just want it to work" path) One tag wraps everything with sensible defaults: :::preview{title="reading-shell with defaults", frame="iframe", height="640px", flush="true", desktopOnly} {{-- The CSS variable on the shell wrapper cascades to the inner spine so it renders narrow enough to fit alongside the article in this iframe; the article below reserves matching padding-right. --}}

Introduction

The shell renders a progress bar, a sidebar TOC, and a bookmark prompt with sensible defaults — drop your article body inside, pass a bookmark key, and the rest is opinionated defaults. The progress bar pins to the very top of this iframe; the spine sits at the right edge; the bookmark arms itself once you've dwelled long enough.

Scroll this preview to see all three primitives respond. The bar fills, the spine highlights the active heading, and after 30 seconds of dwell, the bookmark prompt appears bottom-right (only on a return visit — first visit shows nothing).

The shell wrapper is the 80% case: pass a bookmark key, accept the comfortable density default. For finer control, decompose into primitives and mount each one directly.

Body

Each primitive in the family carries its own Alpine state; nothing communicates between them. That makes the composition robust to changes in any one of them — opt out per-toggle (:spine="false") or pick a density preset (density="compact") without breaking the others.

The four primitives the shell composes by default: reading-progress (the bar), reading-spine (the sidebar TOC), reading-bookmark (the dwell-triggered prompt), reading-meta (time-to-read estimate, off by default). The minimap and TOC primitives are toggleable but disabled in the comfortable density preset — opt in via :minimap="true" / :toc="true".

The density preset (comfortable, compact, minimal) flips per-primitive defaults. compact uses a thinner progress bar and forces the spine to always-md expanded. minimal shows only the progress bar.

Conclusion

For per-primitive customization beyond what toggles + density cover, compose primitives directly. The shell covers the common case; dropping to primitives covers the rest, with no "shell-with-overrides" half-step in between.

The shell's div wrapper is the only structural element it adds. If your layout needs the article body to live inside a flex/grid container or a Livewire boundary, the shell's wrapper might interfere — that's the canonical signal to drop the shell and mount primitives directly.

Click any spine link to smooth-scroll to that heading. Click anywhere else to return reading. The bookmark saves your offset every second; on a real return visit (after 30s+ dwell time), it'll prompt you to resume.

 ::: ## Family contracts These contracts apply uniformly to every primitive in the family. They are documented once here, not duplicated in each primitive section. ### Reduced motion Every transition (bar fill `transform: scaleX`, dot stroke `dashoffset`, spine width / label opacity / tick color-fade, bookmark pill enter / leave, minimap stripe color transitions, smooth-scroll on click / back-to-top) collapses to `0.01ms` under `prefers-reduced-motion: reduce` via the global `@media` block in `dist/wirekit.css`. Values still update on scroll — only the interpolating transition is removed; the value itself jumps to current. ### Print stylesheet All primitives carry a `@media print { display: none !important }` rule scoped via marker classes (`.wk-reading-progress`, `.wk-reading-spine`, `.wk-reading-minimap`, `.wk-reading-bookmark`, `.wk-reading-meta`). Print-friendly for blog-to-PDF workflows — only the article body prints, not the reading chrome. ### The `target` prop convention Every primitive accepts a `target` prop that defaults to `null`. When null, the primitive resolves an internal default per-component: - `reading-progress` `target=null` → tracks viewport scroll - `reading-spine`, `reading-bookmark`, `reading-meta`, `reading-minimap` `target=null` → resolves to `'main, article'` (first-match wins) Pass an explicit CSS selector when your article container isn't `
` or `
` (e.g. `target="#docs-body"`). ### The `wk-reading-*` marker classes Every primitive carries a `wk-reading-{name}` marker class on its root element. Use these for developer CSS overrides without editing the package source. ## Primitives ### Reading Progress A viewport-pinned indicator that fills 0 → 100% as the reader scrolls. Two surfaces share one component: `indicator="bar"` (default — thin horizontal strip) and `indicator="dot"` (circular SVG pinned bottom- right). Both reuse the same Alpine state machine; only the rendered DOM differs. The fill animation uses `transform: scaleX` (bar) / `stroke-dasharray` (dot) — both compositor-only properties, GPU-accelerated, no layout or paint cost. :::preview{title="Bar (default)", frame="iframe", height="480px", flush="true"}

Watch the bar fill as the page scrolls

The reading-progress bar pins to the very top of the iframe (its position: fixed anchors to the iframe's viewport, not the outer page). Scroll inside this preview frame — the bar's fill grows from 0% to 100% as the scroll position moves from 0 to the bottom.

The fill animation uses transform: scaleX — a compositor-only property, so the bar fills smoothly even on low-powered devices without triggering layout or paint. Under prefers-reduced-motion: reduce the transition collapses to 0.01ms; the value still updates on scroll, only the interpolation is removed.

Default height is 3px (height="md"). Pass height="sm" for a 2px hairline or height="lg" for a 5px chunky bar. The color is the accent token by default; pass variant="success" / variant="warning" / variant="danger" for semantic states.

The bar starts hidden until the reader has scrolled past showAfter pixels (default 0). Set a higher value (e.g. :showAfter="100") if you want the bar to appear only after the reader has committed to reading past the article header.

Pass :milestones="true" to fire wirekit:reading-progress:milestone events at 25%, 50%, 75%, and 100%. Useful for analytics or for triggering a "you're halfway through" prompt where it makes sense.

The progress bar lives in its own DOM node and never interferes with the document flow — even when nested inside other components, it takes itself out of layout via position: fixed the moment it mounts.

If your page has a fixed header above the article, set position="bottom" to pin the bar to the viewport bottom instead. Both positions share the same Alpine state machine; only the rendered DOM differs.

For embedded contexts like browser extensions or iframes-within-iframes where the bar should match surrounding text color, pass variant="auto". The fill resolves to currentColor, so the bar inherits whatever color the surrounding context provides.

Keep scrolling — the more text you scroll past, the more visible the bar's fill becomes. By the end of this preview block the bar should be at or near 100%.

The progress bar is the lightest of the reading-* primitives — pure CSS plus a single rAF-throttled scroll listener. No IntersectionObserver, no localStorage, no DOM scanning of headings.

 ::: :::preview{title="Dot indicator", frame="iframe", height="480px", flush="true"}

Watch the dot fill as the page scrolls

Scroll inside this preview frame and the dot's stroke fills clockwise as the scroll position progresses from 0 to the bottom. Same Alpine state machine as the bar variant; only the rendered DOM differs. The dot pins to the bottom-right of the iframe via position: fixed and renders as a circular SVG with a stroke that fills as the reader progresses.

The fill animation uses stroke-dasharray on the SVG circle — also a compositor-only property, GPU-accelerated. The dot doesn't take itself out of layout (it sits in its own fixed-position container), so it never interferes with the article flow below.

Use the dot variant when a horizontal bar would interfere with your layout — for example, if you already have a fixed top nav or a persistent CTA at the top. The dot is also less visually heavy than the bar; some product surfaces want the indicator to be discoverable but not prominent.

Hover the dot to see the percentage tooltip (the percentage is also exposed via the dot's aria-label for screen readers). On touch, the tooltip is suppressed; the percentage is still available via assistive tech.

Pass position="bottom-left" / position="top-left" / position="top-right" to relocate the dot. The default bottom-right follows the convention every messaging app and chat surface uses for "your status indicator".

The dot variant carries the same variant prop as the bar (primary, neutral, success, warning, danger, info, auto) — the color token threading is identical.

Both indicators (bar and dot) ship a @media print { display: none !important } rule via the .wk-reading-progress marker class. Print-friendly; the article body prints clean without progress chrome on every page.

If you need both indicators simultaneously (a bar for "where am I" plus a dot for ambient feedback), mount two <x-wirekit::reading-progress> tags side by side. Both share scroll state via the same plugin; neither knows about the other.

Keep scrolling to see the dot fill. The stroke completes as the reader hits the bottom of the article.

 ::: #### Variants Six canonical values + one runtime-resolved value: | Value | Fill | |---|---| | `primary` (default) | `--color-wk-accent` (brand emphasis) | | `neutral` | `--color-wk-text-muted` (quiet gray) | | `success` / `warning` / `danger` | semantic color tokens | | `info` | visual synonym of `primary` (matches alert/callout pattern) | | `auto` | `currentColor` fallback — for embedded contexts (iframes, browser extensions) where the bar should match surrounding text color | Every variant resolves through `var(--reading-progress-fill, var(--color-wk-X))`, so the `--reading-progress-fill` developer-side token override applies regardless of variant. Set the token at `:root` for a theme-wide override. #### Reading Progress props | Prop | Type | Default | Description | |---|---|---|---| | `position` | string | `'top'` | `top` or `bottom` viewport edge | | `height` | string | `'md'` | `sm` (2px) / `md` (3px) / `lg` (5px) | | `variant` | string | `'primary'` | See "Variants" above | | `intent` | string\|null | `null` | Canonical name for the color axis, accepting the same values as `variant`. Falls back to `variant` when omitted, and wins over it when both are given. | | `showAfter` | int | `0` | Pixel scroll threshold before bar appears | | `target` | string\|null | `null` | CSS selector or null for viewport scroll | | `indicator` | string | `'bar'` | `bar` or `dot` | | `segments` | array\|null | `null` | Fractional 0..1 chapter-marker positions | | `milestones` | bool | `false` | Fire `wirekit:reading-progress:milestone` event at 25/50/75/100% | | `boundary` | `'container'`\|``\|null | `null` | When set to `'container'`, swap `position: fixed` → `position: sticky` so the bar/dot stays inside the nearest positioned, scrollable ancestor. Pass a CSS selector string (e.g. `"#article"`) to additionally assert at runtime that the matched ancestor exists — the Alpine init logs a `console.warn` when the selector matches no ancestor. Required for embedding inside modal bodies, sidebar panes, or preview frames. See [Scoping a primitive to its parent](#scoping-a-primitive-to-its-parent--the-boundary-prop). | | `scope` | string\|null | `null` | Personalization scope | ### Reading Spine > **Looking for canonical layout-wiring?** The [on-page-toc recipe](/blueprints/recipes/on-page-toc) shows the Stripe / Linear / Vercel / shadcn-style sidebar pattern end-to-end: reading-spine next to `
`, CSS variables for sticky offset, integration with a sticky header + breadcrumb, and a working preview. A sidebar mini-TOC that auto-builds from page headings, tracks the reader's scroll position via IntersectionObserver, and expands on hover or focus. :::preview{title="Default spine", frame="iframe", height="640px", flush="true", desktopOnly} {{-- The CSS-variable override narrows the expanded spine width so it fits the iframe gutter; the article below reserves matching padding-right. --}} {{-- .wk-reading-content reserves a responsive inline-end gutter for the fixed-position spine — full width below md (spine hidden), an 11rem gutter at md+ (matching this preview's 10rem expanded spine + 1rem offset via the --reading-content-spine-gutter override). --}}

Overview

The reading-spine is a fixed-position sidebar TOC at the right edge of the iframe. It auto-builds from the headings inside the nearest <article> or <main> ancestor, renders one tick per heading, and tracks the active section via IntersectionObserver as you scroll.

Hover or focus the spine to expand the labels — collapsed it's just a thin column of ticks; expanded it shows full heading text. The expand-on-hover keeps horizontal space minimal until the reader actually wants to navigate.

Tick widths

Tick width encodes heading level: h2 ticks render wider than h3 ticks, which render wider than h4 ticks. This visual hierarchy survives at minified scale — the reader can tell nesting depth at a glance even before expanding.

Levels included default to '2,3' (h2 + h3). Pass levels="'2'" for h2-only (flat outline), or levels="'2,3,4'" for deeper hierarchies. Six levels (h1-h6) are valid; the plugin filters anything outside that range.

Active section detection

The active heading is the LAST heading whose top is at or above the viewport-top offset line (default 96px). This handles tall sections cleanly — a section longer than the viewport becomes "active" as the reader scrolls past its first paragraph rather than waiting for the next heading to enter the viewport.

The IntersectionObserver runs with rootMargin: -96px 0px -90% 0px — narrow band at the viewport top, wide band below. Each callback re-evaluates against live getBoundingClientRect() to find the currently-active item. Cost is ~2ms at 100 headings, well under one frame.

Smooth scroll on click

Click any tick → smooth-scroll to that heading. The URL hash updates via history.replaceState(), not pushState() — back-button still goes to the previous page rather than the previous heading. Saves the user from a multi-press back-button repro to escape the article.

Smooth scrolling is gated by prefers-reduced-motion: reduce — when the OS preference is set, the scroll happens instantly. Same gate applies to the active-state color transitions on the ticks.

Section-changed events

The spine dispatches wirekit:reading-spine:section-changed with details { index, id, text, level } when the active heading changes. Listen with x-on:wirekit:reading-spine:section-changed.window to update the browser tab title, fire analytics on section view, or sync state with a deeper component.

The dispatch is debounced 80ms — rapid scrolling doesn't fire 30 events for transient pass-throughs; only the heading the reader actually paused on triggers a callback.

Mobile behavior

The spine is hidden on viewports under md (768px) by default — hover doesn't exist on touch and the fixed sidebar would crowd a narrow viewport. Pass hideBelow="none" to show the spine even on mobile, useful for the collapsed-tick "I'm in section X" indicator without the expand interaction.

Filter slot: pass any input as the filter slot, two-way bind via x-model="filter". Items hide when their text doesn't match (case-insensitive substring). Useful for very long outlines (e.g. API reference pages with 40+ sections).

 ::: #### Filter slot — canonical worked example Pass any input as the `filter` slot; two-way-bind via `x-model="filter"`. Items hide when their text doesn't match (case-insensitive substring). ```blade ``` #### Reading Spine props | Prop | Type | Default | Description | |---|---|---|---| | `target` | string\|null | `null` | Scroll container to scan; null falls back to `main, article` | | `levels` | string | `'2,3'` | Comma-separated heading levels to include | | `position` | string | `'right'` | `left` or `right` viewport edge | | `expand` | string | `'hover'` | `hover` / `focus` / `always` / `always-md` | | `offset` | string | `'6rem'` | Active-detection threshold | | `hideBelow` | string | `'md'` | Tailwind responsive prefix (`sm`/`md`/`lg`/`xl`/`none`) | | `numbered` | bool | `false` | Hierarchical 1, 2.1, 2.2 labels | | `fillSections` | bool | `false` | Per-tick progress fill via CSS gradient | | `sectionEvents` | bool | `true` | Dispatch `wirekit:reading-spine:section-changed` | | `backToTop` | bool | `false` | Back-to-top pill at the spine bottom | | `boundary` | `'container'`\|null | `null` | When set to `'container'`, swap Tailwind `fixed` → `absolute` so the spine stays inside the nearest positioned ancestor instead of the viewport edge. See [Scoping a primitive to its parent](#scoping-a-primitive-to-its-parent--the-boundary-prop). | | `scope` | string\|null | `null` | Personalization scope | ### Reading TOC Horizontal sticky-strip TOC for marketing landing pages. Sibling to `reading-spine` — same data source (auto-builds from page headings via the same plugin pattern, IntersectionObserver tracks the active section), different rendered shape (a flat row of links across the top or bottom of the article container) and different responsive defaults (mobile-hidden by default). **When to use:** marketing landing pages with 3-4 anchor sections (Hero, Features, Pricing, FAQ) where a vertical sidebar feels excessive. The strip pins to the top of the viewport on scroll, and the link for the currently-visible section highlights via `aria-current="location"`. **When NOT to use:** dense documentation pages with many headings — a horizontal strip overflows fast at viewport widths < 1024px. Reach for `` with `hideBelow="none"` instead, since its collapsed-tick mode works at narrow widths where a horizontal strip cannot. Typical range is three or four anchored sections — a landing page rather than a reference page. ```blade ``` ::: info Works inside your own scroll region If your shell scrolls an inner container rather than the page — a fixed header with `overflow-y: auto` beneath it — the jump finds that container on its own. Nothing to configure. ::: The `offset` prop pushes the sticky position down by the developer's own fixed nav height (e.g. `4rem` to clear a 64px header bar above the TOC). The same value is passed through to the IntersectionObserver rootMargin so active-section detection lines up with the visual position of the strip. :::preview{title="The reading family in one page", frame="iframe", height="640px", flush="true", desktopOnly}

Hero

Marketing landing page section one — a brief outline of what the page covers. The TOC strip pinned to the top of this iframe is sticky; scroll down and watch the active link follow you as each heading crosses the strip's bottom edge.

The strip auto-scans <main> for <h2> elements (default levels="2") and renders one link per heading. No prop wiring required for the common case — drop the tag inside <main>, the rest is automatic.

Each link has aria-current="location" when active. The color comes from --reading-toc-color-active (the accent token by default). Idle state uses --reading-toc-color-idle (text-muted by default). Both transition over 150ms unless reduced-motion is set.

Features

The bullet-pointed pitch. Each feature gets a paragraph or two, all under the same h2. The strip's IntersectionObserver flips the active link as soon as this heading crosses the viewport-top + offset line.

Click the "Hero" link in the strip to smooth-scroll back. The smooth-scroll math accounts for the strip's offset so the destination heading lands just below the strip, not under it. URL hash updates via replaceState — back-button still goes to the previous page, not to the previous anchor.

Per-link max-width truncation defaults to 24ch (--reading-toc-link-max-width). A long heading like "How to manage your team's billing settings" gets truncated to keep the strip from overflowing horizontally on narrow viewports.

Pricing

Three tiers, each with a card. Anchor links from the TOC strip jump straight to this section. The strip stays visible all the way down the page (it's position: sticky; top: 0 by default).

If your page has a fixed nav above the article, pass offset="4rem" on the strip to push the sticky position down by your nav's height. The same value passes through to the IntersectionObserver rootMargin and to the smooth-scroll target math — three concerns, one offset value.

The list is wrapped in overflow-x-auto so a strip with 6+ items still scrolls cleanly without breaking the page layout. On mobile (under sm by default), the strip is hidden entirely — pass hideBelow="none" to show it on mobile if your design accommodates it.

FAQ

Accordion of common questions. Last anchor in the strip. The strip stays visible here too — the reader can jump back to any earlier section without scrolling all the way up.

For pages with more than 5-6 anchored sections, switch to the vertical reading-spine instead. The horizontal strip overflows fast at viewport widths under 1024px, even with per-link truncation. The spine's collapsed-tick mode is the right shape for dense vertical TOCs at narrow widths.

The two primitives (reading-toc and reading-spine) share the same data-collection model — both auto-build from headings via the same Alpine plugin pattern, both track active sections via IntersectionObserver. Only the rendered shape differs.
::: #### A11y / motion / print - Real `` links inside a `