Transitions

Stagger

Reveals children one after another with a transition-delay per index. Optionally waits for the group to scroll into view first.

  • list
  • reveal
  • intersection-observer

Preview

Deploy pipeline3 checks passing
Design tokenssynced 4m ago
Auth service2 open alerts
Search indexrebuilding
CDN cache94% hit rate

Usage

<Stagger step={70} whenVisible>
  {rows.map((r) => <Row key={r.id} {...r} />)}
</Stagger>
"use client";

import { Children, useEffect, useRef, useState } from "react";
import { cn } from "@/lib/cn";

export interface StaggerProps {
  children: React.ReactNode;
  /** ms between each child. */
  step?: number;
  duration?: number;
  delay?: number;
  distance?: number;
  direction?: "up" | "down" | "left" | "right";
  /** Wait until the group scrolls into view before playing. */
  whenVisible?: boolean;
  className?: string;
}

const travel = {
  up: (d: number) => `translateY(${d}px)`,
  down: (d: number) => `translateY(${-d}px)`,
  left: (d: number) => `translateX(${d}px)`,
  right: (d: number) => `translateX(${-d}px)`,
};

/** Reveals children one after another — the cheapest way to make a list land well. */
export function Stagger({
  children,
  step = 60,
  duration = 420,
  delay = 0,
  distance = 10,
  direction = "up",
  whenVisible = false,
  className,
}: StaggerProps) {
  const host = useRef<HTMLDivElement>(null);
  const [play, setPlay] = useState(!whenVisible);

  useEffect(() => {
    if (!whenVisible || !host.current) return;
    const io = new IntersectionObserver(
      ([entry]) => entry.isIntersecting && (setPlay(true), io.disconnect()),
      { threshold: 0.15 },
    );
    io.observe(host.current);
    return () => io.disconnect();
  }, [whenVisible]);

  return (
    <div ref={host} className={cn(className)}>
      {Children.map(children, (child, i) => (
        <div
          style={{
            opacity: play ? 1 : 0,
            transform: play ? "none" : travel[direction](distance),
            transition: `opacity ${duration}ms var(--ease-out-quint), transform ${duration}ms var(--ease-out-quint)`,
            transitionDelay: `${delay + i * step}ms`,
          }}
        >
          {child}
        </div>
      ))}
    </div>
  );
}

export default Stagger;