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
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.
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
| Prop | Type | Default | What it does |
|---|---|---|---|
steps | StoryStep[] | none | Required. 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) => void | none | Optional. No default. Called with the step id when a step becomes active. |
paused | boolean | false | Universal pause prop. Stops tracking the scrolled step: the active step stays where it is. |
nonce | string | none | Optional CSP nonce forwarded to the internal scoped <style> element. |
className | string | "" | Optional CSS class names to apply to root container. |
style | React.CSSProperties | none | Optional. No default. Inline styles for the root container. |
ref | React.Ref<HTMLDivElement> | none | Receives 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.
| Measure | Result |
|---|---|
| Size, gzip | 2.81 KB at load, 0.02 KB loaded later |
| Layout shift | 0 |
| Frames when nothing should move | off screen 0, hidden tab 0, reduced motion 0 |
| axe accessibility scan | 0 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.
| Environment | Tier | Result | Date | Notes |
|---|---|---|---|---|
| Chromium Desktop (SwiftShader) | 3 | pass | 2026-10-21 | 16 passed, 0 failed |
| Chromium Mobile (Pixel 7 emulation) | 2 | pass | 2026-10-21 | 15 passed, 0 failed |
| Firefox Desktop | 3 | pass | 2026-10-21 | 15 passed, 0 failed |
| WebKit Desktop | 3 | pass | 2026-10-21 | 15 passed, 0 failed |
| WebKit Mobile (iPhone 14 emulation) | 2 | pass | 2026-10-21 | 15 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.
| Tier | What it does |
|---|---|
| T3 Full | Same as tier 0; layout depends on viewport width, not tier |
| T2 Standard | Same as tier 0; layout depends on viewport width, not tier |
| T1 Lite | Same as tier 0; layout depends on viewport width, not tier |
| T0 Static | Not 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 yournonce), or callinitMotionReady()in Vite. - Sets inline
styleattributes, so allowstyle-src-attr 'unsafe-inline'.