Scrollytelling Stage

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

<ScrollytellingStage />

Installation

Usage

Each ScrollytellingStep uses scene to describe the state the stage on the left should show when you scroll to that step; as you scroll, the stage tweens and morphs between the scenes of adjacent steps.

import {
  ScrollytellingStage,
  ScrollytellingStep,
} from "@/components/ui/scrollytelling-stage";

<ScrollytellingStage>
  <ScrollytellingStep title="A steady start" scene={{ data: [30, 42, 38, 46, 40] }}>
    <p>Baseline: weekly activity stays roughly flat.</p>
  </ScrollytellingStep>

  <ScrollytellingStep
    title="Midweek surge"
    scene={{
      data: [30, 55, 74, 60, 44],
      annotation: { at: 2, label: "Wednesday peak" },
    }}
  >
    <p>After the new feature shipped, Wednesday produced a single-day peak.</p>
  </ScrollytellingStep>

  <ScrollytellingStep
    title="Carried through"
    scene={{
      data: [34, 58, 70, 82, 76],
      highlight: [3, 4],
      annotation: { at: 3, label: "Holding at a high" },
    }}
  >
    <p>The highlighted range shows Thursday and Friday reaching new highs.</p>
  </ScrollytellingStep>
</ScrollytellingStage>;

If the scrolling happens inside a fixed-height nested overflow-y-auto container, pass that container's ref to container:

const scrollerRef = React.useRef<HTMLDivElement>(null);

<div ref={scrollerRef} className="h-[300px] overflow-y-auto">
  <ScrollytellingStage container={scrollerRef}>
    {/* ...steps */}
  </ScrollytellingStage>
</div>;

When you need a fully custom stage, use renderStage instead (replacing the built-in data chart); it receives the current activeIndex and the continuous step progress (a MotionValue, from 0 to the number of steps minus 1):

<ScrollytellingStage
  renderStage={({ activeIndex, progress }) => (
    <MyCustomStage step={activeIndex} progress={progress} />
  )}
>
  {/* ...steps */}
</ScrollytellingStage>

Props

ScrollytellingStage

ScrollytellingStep

StageScene

How it works

• useScroll tracks the scroll progress of the step column on the right and converts it into a continuous step value (from 0 to the number of steps minus 1), which is the single source driving every tween — so the bar heights, the highlight band, and the annotation line always deform in sync.
• The highlight band and the annotation line use currentColor, so a text-* on stageClassName sets the accent color for everything at once.
• Bars near the annotation line brighten to the accent color, producing a spotlight effect that travels with the scroll.
• For scenes missing a highlight or an annotation, the matching graphic fades out smoothly, so the morph never jumps.

Accessibility

• When the user has "reduce motion" enabled at the system level, the stage switches instantly from step to step (no tween, no transition), with the layout and content completely unchanged.
• The stage on the left carries role="img" and an aria-label describing the current step; the SVG graphics inside are hidden from assistive technology.
• The steps are a semantic ordered list (<ol> / <li>) with the active step marked aria-current="step" and emphasized through opacity and its title; the keyboard simply uses the browser's native scrolling to read through them in order.