Skip to the content

Motion

stagger

A container whose items fade and move into place one after another when it scrolls into view.

Motion and transitions

When to use it

A grid of cards, a feature list, a row of logos. For one block use reveal; for the words of a heading use text-reveal.

See it working

The demonstration the browser checks drive, with the keyboard as well as the pointer. More of it is on the Motion and transitions page.

Reveal, stagger, text reveal

Words arrive one after another when they come into view.

1
2
3
4

Content already on screen when the page loads stays put; only what scrolls in is animated.

Number ticker and presence

128,450

Mounted and unmounted with a transition

Tilt, spotlight, magnetic

Tilt (move the pointer)
Spotlight

Shared element and view transition

1234

Scroll scene

A section that holds still

while the story moves with the scroll.

Then the next beat

Under reduced motion it is a plain stack.

Add it

npx shadcn@latest add @rivier-ui/stagger

The registry is named once in components.json: see Installation.

Example

Import it from @/components/motion/stagger.

<Stagger className="grid gap-4 sm:grid-cols-3" interval={0.08}>
  <StaggerItem><Card>Design</Card></StaggerItem>
  <StaggerItem><Card>Build</Card></StaggerItem>
  <StaggerItem><Card>Launch</Card></StaggerItem>
</Stagger>

What it needs

A client component: it uses state, effects or browser behaviour. No packages beyond React.

It imports

Source

The whole file. Once copied it is yours: the registry item holds the same text.

src/components/motion/stagger.tsx
"use client";
/**
 * @name stagger
 * @category motion
 * @description A container whose items fade and move into place one after another when it scrolls into view.
 * @when A grid of cards, a feature list, a row of logos. For one block use reveal; for the words of a heading use text-reveal.
 * @example
 * <Stagger className="grid gap-4 sm:grid-cols-3" interval={0.08}>
 *   <StaggerItem><Card>Design</Card></StaggerItem>
 *   <StaggerItem><Card>Build</Card></StaggerItem>
 *   <StaggerItem><Card>Launch</Card></StaggerItem>
 * </Stagger>
 */
import { useImperativeHandle, useRef, type ComponentProps } from "react";
import { cn } from "@/lib/cn";
import { useEntrance, type EntranceDirection, type EntranceOptions } from "@/lib/motion";

export type StaggerProps = ComponentProps<"div"> & {
  /** Seconds between one item and the next. Default 0.08. */
  interval?: number;
  /** Seconds before the first item. Default 0. */
  delay?: number;
  /** Seconds each item takes. Default: the scene duration (0.7). */
  duration?: number;
  /** The way each item travels as it arrives. Default "up". */
  direction?: EntranceDirection;
  /** How far each item travels, in pixels. Default 16. */
  distance?: number;
  /** Play once (default), or again each time the container comes back into view. */
  once?: boolean;
  /** Also play when it is already in view as the page loads (items are hidden first). Default false. */
  playOnLoad?: boolean;
  /** Grows or shrinks the viewport edge used for "in view", as a CSS margin. */
  margin?: EntranceOptions["margin"];
  /** How much of the container must be in view: "some" (default), "all", or a fraction. */
  amount?: EntranceOptions["amount"];
};

/** The items of this container in document order; items of a Stagger nested inside belong to that one. */
function itemsOf(root: HTMLElement): HTMLElement[] {
  return Array.from(root.querySelectorAll<HTMLElement>('[data-slot="stagger-item"]')).filter(
    (item) => item.closest('[data-slot="stagger"]') === root,
  );
}

/** The container is never transformed and is the element watched; only the items move. */
export function Stagger({
  className,
  interval = 0.08,
  delay = 0,
  duration,
  direction = "up",
  distance = 16,
  once = true,
  playOnLoad = false,
  margin,
  amount,
  ref,
  ...props
}: StaggerProps) {
  const rootRef = useRef<HTMLDivElement>(null);
  useImperativeHandle(ref, () => rootRef.current as HTMLDivElement, []);
  useEntrance(rootRef, itemsOf, {
    direction,
    distance,
    duration,
    delay: (index) => delay + index * interval,
    once,
    playOnLoad,
    margin,
    amount,
  });

  return <div ref={rootRef} data-slot="stagger" className={cn(className)} {...props} />;
}

/** One revealed item. It can sit at any depth inside its Stagger; the order is the order in the document. */
export function StaggerItem({ className, ...props }: ComponentProps<"div">) {
  return <div data-slot="stagger-item" className={cn(className)} {...props} />;
}