Scroll stories and scroll effects

Pick a scene#

Scroll stories and scroll journeys tell across several screens, a section holds and its content changes with the scroll.

Scroll effects and reveals and transitions are shorter. They make a transition or a headline memorable and hand the page back quickly.

Use a scene#

Scenes take content through props like any component. Pictures go in as media or items[].media, chapters as a list. In Astro a scene gets a client directive so it runs while scrolling.

import { StickyStack } from '@/components/ui/sticky-stack';
import { PinnedMedia } from '@/components/ui/pinned-media';

<StickyStack
  variant="process"
  title="From the first call to the launch"
  items={[
    { eyebrow: 'Week 1', title: 'Workshop', text: 'We sort goals, pages and content in one afternoon.' },
    { eyebrow: 'Week 2', title: 'Design', text: 'Three screens in your colors, ready to click.' },
    { eyebrow: 'Week 4', title: 'Launch', text: 'Live on your domain, with analytics and a handover.' },
  ]}
/>

<PinnedMedia
  variant="pan-zoom"
  title="A walk through the bakery"
  media={<img src="/bakery-plan.avif" alt="Floor plan of Lindner Bakery" width={1600} height={1000} />}
  chapters={[
    { title: 'The oven', text: 'Stone oven, fired at four every morning.', focus: { x: 0.28, y: 0.4, zoom: 1.8 } },
    { title: 'The counter', text: 'Twenty kinds of bread, sliced while you wait.', focus: { x: 0.7, y: 0.62, zoom: 1.5 } },
  ]}
/>

<!-- Without a directive the finished, calm layout shows -->
<StickyStack variant="process" items={items} />

<!-- With a directive the scene runs while scrolling -->
<PinnedMedia client:visible variant="pan-zoom" chapters={chapters} media={media} />

In the preview#

On the page of a category the preview of a scene gets a fixed window height and scrolls inside itself, so stacks, chapters and zooms run exactly as on your page. Scroll with the mouse or trackpad over the preview to see them.

A preview spots scenes by data-kit-viewport. Scenes pass every extra attribute on to their outer element, so you can mark your own demos too.

Reduced motion and no JavaScript#

Every scene renders its finished layout on the server. Without JavaScript and with reduced motion it stays that way, every chapter, picture and number stands in order and reads completely. What would only make sense through motion gets a calm form of its own there, such as a row you swipe yourself instead of the guided ride.

On phones many scenes have a layout of their own, such as a swipe row instead of the sideways ride or a timeline that runs down. Links in late chapters stay in the tab order, and scenes with a pinned track scroll to the matching spot.

Performance#

• Progress runs as the CSS variable --p, not through React state. A scroll frame triggers no render.
• Only transform, opacity and clip-path move, never anything that shifts the layout.
• Heights of pinned tracks are measured on start and on resize, never while scrolling.
• Scenes with drawn pictures keep the variable on small elements without pictures, so the picture is not repainted on every frame.
• Give pictures a fixed width and height and a light format such as AVIF, a pinned scene shows them large and for long.

Your own scene#

Every scene shares scroll-scene. The same helpers carry a small scene of your own.

import { useLive, useSceneProgress, seg } from '@/components/ui/scroll-scene';

export function Statement() {
  // Runs only in the browser, from tablet up and without reduced motion
  const live = useLive('(min-width: 768px)');
  // Writes the progress from 0 to 1 as --p onto the element
  const ref = useSceneProgress<HTMLElement>(live, { mode: 'enter' });
  return (
    <section ref={ref} className="py-24">
      <h2 style={{ opacity: `calc(0.25 + 0.75 * ${seg(0, 0.7)})`, transform: `translateY(calc((1 - ${seg(0, 0.7)}) * 24px))` }}>
        Bread takes time. So do we.
      </h2>
    </section>
  );
}

The ground rules for motion in the kit are under Motion.