Reading Strand

ReadingStrand — reading progress as the brand's draw verb: a single strand-a line at the top of the viewport that draws itself as the reader moves through the piece. BRAND_PHILOSOPHY: one strand, drawn — never faded.

feedbackclientuiv1.0.0

Reading Strand — live renderprimitives-readingstrand--default ↗

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL

npx shadcn@latest add https://ds.interlace.tools/r/reading-strand.json

With the @interlace alias

npx shadcn@latest add @interlace/reading-strand

History

This component is at v1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

Unreleased1 entry

Addedminor
ReadingStrand — reading progress as the brand's draw verb A single strand-a line pinned to the viewport top that draws itself as the reader moves through the piece. Progress is state coupled to the reader's own scroll (nothing animates on its own — no reduced-motion variant to gate). Real role="progressbar" 0–100; measures at most once per frame via a passive listener; the fill moves with compositor-only transform: scaleX. target names the article element by id so server pages need no client seam; falls back to the whole document. SSR renders scaleX(0) — zero CLS.

Import

2 named exports — pull the parts you need.

Public API

import { ReadingStrand, readingProgress } from '@/components/ui/reading-strand';

Anatomy

Extracted from the primitive's JSDoc header. The source is the only documentation that can't drift.

One fixed track (transparent by default — the page shows through)
holding one strand that scales horizontally from the left edge.
`transform: scaleX(p)` keeps updates compositor-only: no layout, no
paint storms on scroll (R25). SSR renders `scaleX(0)` — zero CLS.
### API parity (R17)
No MUI/shadcn equivalent exists; the closest ecosystem shape is a
scroll-linked progress bar. Deviations from those: the element is a
real `progressbar` (they are usually decorative divs), and the read
span is declared by ELEMENT ID rather than a ref so server pages can
render it without a client seam just to thread a ref (the blog's RSC
boundary lesson, blog#176).
### A11y (R26)
`role="progressbar"` + "Reading progress" name, `aria-valuenow`
0–100. Value changes never announce unless queried — no live-region
spam. The strand is informative but never the ONLY carrier: pages
still state reading time in text (COLOR_PHILOSOPHY / size-is-not-
the-only-carrier, same contract as TimelineMap weights).

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

ReadingStrandProps

Also accepts every <div> attribute.

Prop	Type	Description
target	string	Stable selector for E2E tests; consumer provides — no default (R5). / 'data-testid': string; /* id of the element whose vertical span maps to 0→1 (the article body, not the page chrome). Falls back to the whole document when omitted or not found. The target should have measurable height: a zero-height element (a container that hasn't populated yet) is a span shorter than the viewport, and reads as fully read.
label	string	Accessible name of the progressbar. @default "Reading progress"

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour: Native element semantics — no interaction layer to get wrong.
Focus ring (WCAG 2.2 SC 2.4.13): Not focusable — no focus indicator required.
Reduced motion: Animation is gated on prefers-reduced-motion.
ARIA in the source: role="progressbar"
aria-label
aria-valuemax
aria-valuemin
aria-valuenow

Dependencies

Base UI primitive: Native / no Base UI dependency
Lucide icons: none
NPM dependencies: none
Registry dependencies: @interlace/theme
@interlace/cn

Source

The full implementation — components/ui/reading-strand.tsx once installed.

150 lines · TypeScript

github ↗

'use client';

import * as React from 'react';

// @interlace/reading-strand v1.0.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/reading-strand
// What changed since: https://ds.interlace.tools/c/reading-strand#history
// Generated banner — keep it, the upgrade diff reads this version.

import { cn } from '@/lib/utils';

/**
 * ReadingStrand — reading progress as the brand's draw verb: a single
 * strand-a line at the top of the viewport that draws itself as the
 * reader moves through the piece. BRAND_PHILOSOPHY: one strand, drawn —
 * never faded.
 *
 * ### prefers-reduced-motion — considered, deliberately not gated
 *
 * Progress here is STATE coupled 1:1 to the reader's own scroll

…130 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/reading-strand.json