Scroll Timeline Chronicle

Quick Start

1. Add to your HTML <head>:

Code snippet omitted: it ships with the download.

2. Add the chronicle to your <body>:

Code snippet omitted: it ships with the download.

3. Add before the closing </body> tag:

Code snippet omitted: it ships with the download.

The script finds every [data-chronicle], builds the digit reels and rail nodes, adds is-live, pins the stage and scrubs the whole composition from one ScrollTrigger.

Using It With Your Own Design

What the effect actually requires

1. The data hooks, not the class names. script.js only ever queries data- attributes. Every chron__* class belongs to the stylesheet and can be renamed or replaced wholesale.
2. [data-chron-entry] elements with a four-digit data-year. Anything can live inside them; the script never looks. Two entries is the minimum.
3. [data-chron-stage] around them. This is the element that gets pinned, so it must be the full-height frame you want the reader to look at.
4. [data-chron-list] as the stacking parent. In the live layout every entry occupies the same grid cell (grid-template-areas: 'stack' with align-content: center), so they are all centred on top of one another and the script's y offsets fan them out. The parent needs perspective for the depth falloff to read.

What is only the demo's CSS

The spine, the giant year, the rail nodes and the tick ray are all optional. Delete [data-chron-year], [data-chron-rail], [data-chron-head] or [data-chron-ray] and the script skips that channel — the entries still snap and fall back in depth. The jump chips in the toolbar are likewise optional; keep them if you want a keyboard route through the chronology.

Non-obvious CSS the effect depends on

• The base styles are the no-JS design. The chronicle is authored as an ordinary readable <ol>; the pinned, stacked layout lives entirely under .chron.is-live, a class the script adds only in the motion branch. This is also why reduced motion needs no separate work: the class is never added, so the plain list is what a reduced-motion reader gets. Do not move the live rules out from under is-live.
• overflow: hidden on the stage. Entries three steps away are still positioned, just faded; without the clip they extend past the frame.
• The digit reel geometry. Each [data-chron-year] slot is overflow: hidden, height: 1em, and its reel is ten 1em cells with line-height: 1. The script sets yPercent: -value * 10, so any change to the cell height must keep all ten cells identical. Slot width must clear the widest digit's ink or the reel clips glyph sides instead of masking the roll.
• Three nested elements at the spine head. [data-chron-head] carries the travelling y, [data-chron-stretch] carries the velocity stretch, [data-chron-pop] carries the handoff pop. Collapsing them into one element makes the three fight over transform.

Theming

The stylesheet is a dark ruled archive: the site's deep (--page: #141414) and chalk (--ink: #f1efea), hairline rules and one accent, yellow (--accent: #fff500, with --accent-ink: #141412 for anything set on it). The accent sits on exactly two things: the odometer year and the head that travels the spine, which is the reading band's marker. The spine itself, the ticks and the drawn length are chalk. The active record is told apart by weight, scale, depth and blur, never by colour.

Every fade composites toward the ground, and that is the one thing to be careful with when repointing this. Neighbouring entries are faded with 1 - ad * 0.32 in the script and sit around 0.68 opacity with a 3.5px blur, which is the point where they still read as shapes without competing with the active entry. The quiet inks (--ink-dim, --ink-faint) are chosen so the entry either side of the head still clears 4.5:1 after that fade; if you move to a light ground, re-measure both before relaxing them, because a faded glyph loses contrast faster on white than on a dark ground.

• The spine head is a slab laid across the margin, a cursor on a ruler, rather than a dot, because a dot reads as a status light. It is also the shape the velocity stretch wants: squashing a bar reads as a smear, where squashing a round or diamond mark reads as a wobble.
• The composition avoids the circle and the diagonal throughout: the margin ticks are rules, the prompt mark is a short rule, the head is a slab, and passed ticks lengthen rather than filling in. Everything is set at right angles, which is what keeps it reading as a ruled sheet rather than a dashboard.
• The year index in the toolbar is plain text with no visible box, but each year carries a min-width/min-height press target so it still clears the 24px floor. Strip those and the index fails target-size on a phone.
• The odometer sits above the stacked list (z-index: 3, pointer-events: none), so a faded neighbour passing behind it is covered rather than ghosted through the digits. It is parked in the corner below the reading band and the active entry is centred, so the two never meet at the frame sizes the stage is designed for; if your entries run much longer than the demo's, shrink the year before you let them overlap.
• The ruled margin is a scrubber. Every tick is a real <button> that seeks to its entry, with the year riding out of the margin on hover so the control says where it is going before it goes. Three things make it actually work, and all three are easy to lose:
  • .chron__list is inset: 0 over the whole stage and comes after the spine in the DOM, so the spine needs z-index: 2 to sit above it. Without that the ticks respond to a scripted .click() and are completely dead to a real pointer, and the failure looks like nothing at all is wired up.
  • The head slab and the handoff ray are decoration, so both are pointer-events: none. The head parks on a tick, and until it was excluded that tick was the one you could never press.
  • The tick is 1.5px of hairline; the press target is a padded ::after. It is sized to just under half the gap between ticks, so it clears the 24px floor without one tick stealing its neighbour's presses.
• The tick buttons are aria-hidden and tabindex="-1" on purpose. They duplicate the year index above them exactly, and making them focusable would put all thirteen years in the tab order twice for no added capability. Keyboard and screen reader users get the same navigation from the index; this is a pointer shortcut and nothing more.

Typography is Mona Sans throughout, loaded from Google Fonts with the four weights the demo uses (400 body, 500 labels, 600 titles, 700 folio and year). The odometer slots are a fixed 0.74em wide, measured against Mona Sans's bold digits; a narrower face can tighten that, a wider one must widen it or the reel clips the glyph sides. The folio number and the year are set without tabular-nums on purpose: Mona Sans slashes its tabular zero, which reads as instrument chrome, and the slots are fixed-width anyway.

Options

Set on the [data-chronicle] element.

data-gap is the one value your copy decides. Entries are absolutely positioned and offset by gap x stage height, so the gap has to clear the tallest entry or a neighbour's last line lands on the next entry's title. The default 0.3 suits a one-sentence entry. A paragraph of four or five lines wants about 0.46, which is what the demo runs: thirteen entries at 48 to 72 words each. Nothing warns you about this, because an overlapping entry is still faded and blurred and reads as intentional depth until you look at the line that has gone through a heading. Set your longest entry first, scroll to it, and raise the gap until it clears.

Per-entry: data-year (four digits) on each [data-chron-entry].

The jump buttons may sit outside the chronicle (a toolbar, a sidebar). The script looks inside [data-chronicle] first and falls back to a document-wide lookup, and keeps aria-current on them in step with the active entry.

Accessibility

• Reduced motion: gsap.matchMedia() never adds is-live, so the chronicle stays a plain, fully readable list in document order. Nothing is hidden and nothing is pinned.
• Without JavaScript: identical. The live layout is the enhancement, not the baseline.
• Keyboard: the jump controls are real <button> elements and carry aria-current. They scroll the page, so the reader's focus and scroll position stay in agreement.
• Announcements: [data-chron-status] is a visually hidden role="status" region updated with the active year at each handoff.
• Motion budget: the velocity stretch is clamped by data-lean and decays on a frame-rate independent curve, so a fast flick cannot leave the column stretched.

Performance

• One pinned ScrollTrigger drives every channel, so nothing can drift out of sync.
• The blur value is quantised to half a pixel and the filter string is only written when it changes, which is what keeps a full chronicle of simultaneously filtered elements affordable. The demo runs thirteen, which is the length a real company history tends to be; only the entries within three steps of the index carry a blur at all, so the cost is set by the falloff window and not by the entry count.
• The velocity ticker is gated to the viewport by a second ScrollTrigger and removes itself if the chronicle leaves the document.
• Keep the entry count modest. Every entry is measured each frame; a hundred-item changelog wants pagination, not a hundred entries.

Dependencies

• GSAP 3.15.0
• Mona Sans (Google Fonts; swap freely, see Theming)
• ScrollTrigger
• Lenis 1.3.17 (optional; smooth scroll is opt-out with data-smooth="off" on <html> or ?smooth=off in the URL)

Browser Support

Chrome, Firefox, Safari and Edge, current versions. The depth falloff uses translateZ with perspective and a blur() filter; both degrade to a plain fade in anything that does not support them.