Skip to content

scroll-section · HTML and CSS

StickyScrollStory

A story told in steps: the text scrolls while its picture stays beside it.

Sticky media column with scrolling steps

  • HTML and CSS
  • Reduced motion: opacity-only
  • 2.81 KB gzip
  • Layout shift 0
View the source Spec sheet as Markdown

Install

Install
pnpm dlx shadcn@4.21.1 add @frictionborn/sticky-scroll-story

Playground

Scroll inside the frame. Below the stacking breakpoint the steps stack with their media.

Your code
import { StickyScrollStory } from "@/components/ui/sticky-scroll-story";

<StickyScrollStory steps={steps} />

In a full example

The full example loads as you scroll to it.

Accessibility

  • DOM order matches reading order. The active step has aria-current='step'. Image media (media.type 'image') gets alt from media.alt, falling back to the step title. Custom media (media.content) gets no alt: supply accessible text inside the content yourself. Each step's media is rendered twice (sticky column and inline mobile copy); only one is visible at a time.
  • Keyboard: Native focus order and keyboard scrolling; the component adds no focusable elements
  • Touch: Stacked layout at viewport width 768px and below, with media shown inline under each step
  • WCAG criteria it is built for: 1.3.1, 1.3.2, 2.2.2

Props

PropTypeDefaultWhat it does
stepsStoryStep[]noneRequired. Array of { id: string; title: string; description: string; badge?: string; media: { type?: "image" | "custom"; src?: string; alt?: string; content?: React.ReactNode } }.
mediaPosition"left" | "right""right"Alignment of the sticky media column relative to the text narrative.
onStepChange(stepId: string) => voidnoneOptional. No default. Called with the step id when a step becomes active.
pausedbooleanfalseUniversal pause prop. Stops tracking the scrolled step: the active step stays where it is.
noncestringnoneOptional CSP nonce forwarded to the internal scoped <style> element.
classNamestring""Optional CSS class names to apply to root container.
styleReact.CSSPropertiesnoneOptional. No default. Inline styles for the root container.
refReact.Ref<HTMLDivElement>noneReceives the root <div>.

Measured on the bench

Measured by the automated bench at commit 801163e on 2026-10-21. These numbers are written by the bench, never by hand.

MeasureResult
Size, gzip2.81 KB at load, 0.02 KB loaded later
Layout shift0
Frames when nothing should moveoff screen 0, hidden tab 0, reduced motion 0
axe accessibility scan0 serious, 0 critical

Browsers it ran in

Automated Playwright runs, some with device emulation. Results from physical phones and tablets are still pending, so none are listed.

EnvironmentTierResultDateNotes
Chromium Desktop (SwiftShader)3pass2026-10-2116 passed, 0 failed
Chromium Mobile (Pixel 7 emulation)2pass2026-10-2115 passed, 0 failed
Firefox Desktop3pass2026-10-2115 passed, 0 failed
WebKit Desktop3pass2026-10-2115 passed, 0 failed
WebKit Mobile (iPhone 14 emulation)2pass2026-10-2115 passed, 0 failed

On different devices

Reduced motion (opacity-only): Media swaps are instant (inactive media is hidden with opacity 0 and transitions are disabled, so there is no fade); no translation or parallax. Server HTML keeps all media visible.

TierWhat it does
T3 FullSame as tier 0; layout depends on viewport width, not tier
T2 StandardSame as tier 0; layout depends on viewport width, not tier
T1 LiteSame as tier 0; layout depends on viewport width, not tier
T0 StaticNot gated by tier: sticky two-column layout above 768px, stacked at 768px and below (same at every tier)

Content Security Policy

  • Works without 'unsafe-eval'.
  • Uses the reveal gate ([data-motion="ok"]): render <MotionReadyScript /> in <head> (with your nonce), or call initMotionReady() in Vite.
  • Sets inline style attributes, so allow style-src-attr 'unsafe-inline'.

Goes well with