Skip to content
caliper ui docs
DemoSign inGet Pro

Pro

Image sequence

A film scrubbed by the page: the frames stay pinned while you scroll through the section, each scroll position showing its frame, forward or back. Frames load coarse to fine, so the nearest loaded one stands in until its neighbour arrives.

Pro
pnpm dlx shadcn@latest add @caliper/image-sequence

Scroll inside the panel to move the camera in, and back to pull out.

The harbour at first light

End of the sequence.

Installs components/ui/image-sequence.tsxDepends on none beyond ReactMotion shared motion tokens

When to use

Use it for

  • Product reveals and explainers where scrolling should turn the object or move the camera.
  • Before and after stories told in many steps.

Skip it when

  • Video people want to watch at its own pace; use a player.
  • Pages on slow connections without a light set of frames.

Decisions

Why it is built this way, so you know what to keep when you change your copy.

Behaviour

Coarse to fine
Frames load in halving steps (first, middle, quarters…), so any scroll position soon has a close frame.
Only the scroll moves it
Nothing plays on its own, so it stays as it is under reduced motion: the reader drives every frame.

Styling

Sized by its stage
Set --iseq-h for the stage and length for how many stage heights the scroll lasts; --iseq-top sets where it pins.

Installation

terminal
pnpm dlx shadcn@latest add @caliper/image-sequence

Adds its 4 files to components/ui/, each with its own stylesheet, and installs their packages. Pro installs with your access token, set up once per project. See Pro access. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage

Import it from your copy of the source. The example behind the preview comes with the source. It is built from ImageSequence and frameOrder.

example.tsx
import { ImageSequence, frameOrder } from "@/components/ui/image-sequence"

The worked example comes with Pro

The 20-line example behind the preview opens here, ready to copy.

  • 576 Pro parts, blocks and page templates, all with source
  • $199 once, with a year of updates. What you have stays yours
  • A full refund within 14 days if it is not for you
Checking your licence…

API reference

ImageSequence

component

Also accepts the native props of its root element and a ref.

PropTypeDefaultDescription
frames *string[]—Frame URLs in order.
alt *string—What the sequence shows, read in place of it.
lengthnumber2.5How long the scroll through it is, in stage heights.
children((progress: number) => ReactNode)—Laid over the frames, e.g. a caption that changes with the scroll. Receives progress 0 to 1.

frameOrder

component

No props of its own; it accepts the native props of its root element.

Accessibility

It exposes img semantics, with aria-label kept in step with state.

No custom key handling; Tab and the native activation keys do the work.

Motion

Transitions use the shared duration and easing tokens. Under prefers-reduced-motion those tokens collapse to instant and travel distances go to zero, so state changes still happen without movement.

All Media examples