Staggered Lists

Relevant source files

The following files were used as context for generating this wiki page:

• src/variants/stagger.ts
• src/hooks/useAnimationSequence.ts
• src/variants/cyber.ts
• src/hooks/useReducedMotion.ts
• src/variants/scale.ts
• src/variants/fade.ts

Staggered lists in the @pcstyle/motion library are implemented using a combination of Framer Motion variants and custom hooks to create orchestrated entry and exit animations for groups of elements. By leveraging a parent-child relationship in the animation tree, the library allows for sequential timing offsets where each item in a list appears after its predecessor with a defined delay.

The system is designed to support various speeds (fast, slow), directions (reverse), and initial delays, while also providing specialized item-level transitions like sliding, scaling, or cyberpunk-themed terminal typing effects.
Sources: src/variants/stagger.ts:1-41, src/variants/cyber.ts:31-38

Core Animation Architecture

The staggering logic relies on the Framer Motion "variants" pattern. A parent container defines a transition orchestration property—specifically staggerChildren—which propagates the "visible" or "hidden" state to its children with a time offset.

Staggered List Flow

The following diagram illustrates how a parent container triggers sequential animations in its children.

The parent container manages the transition timing, while each child item defines its own motion path (e.g., sliding up or scaling in).
Sources: src/variants/stagger.ts:6-12

Container Configurations

The library provides several pre-configured container variants to handle different visual rhythms and requirements.

Variant Name	Stagger Delay	Special Behavior	Source
staggerContainer	0.1s	Standard sequential entry	src/variants/stagger.ts:6-12
staggerFast	0.05s	Rapid fire entry	src/variants/stagger.ts:14-20
staggerSlow	0.2s	Deliberate, slow reveal	src/variants/stagger.ts:22-28
staggerReverse	0.1s	Bottom-to-top animation (staggerDirection: -1)	src/variants/stagger.ts:30-36
staggerDelayed	0.1s	Starts after initial delayChildren: 0.3s	src/variants/stagger.ts:38-44

Item Variants

While the container controls the when, item variants control the how. These variants are applied to individual list elements.

• staggerItem: A standard vertical entrance, moving from y: 20 to y: 0 while fading in.
• staggerItemScale: A focal entrance where the item grows from 80% to 100% scale.
• staggerItemSlide: A horizontal entrance sliding from the left (x: -20).
• terminalType: A specialized cyberpunk variant that uses a dynamic delay based on index (i * 0.05) to simulate typing.

Sources: src/variants/stagger.ts:49-65, src/variants/cyber.ts:31-38

Imperative Sequencing

For complex layouts where declarative variants are insufficient, the useAnimationSequence hook allows for programmatic staggering using the stagger function from Framer Motion.

// Example of how the hook processes staggered steps
if (step.options?.stagger) {
  options.delay = stagger(step.options.stagger);
}

Sources: src/hooks/useAnimationSequence.ts:31-34

Accessibility and Reduced Motion

The system includes a safeguard for users who prefer reduced motion. The useAccessibleMotion hook can intercept staggered variants and replace them with simplified fades, preventing potentially disorienting motion while maintaining the logic of the list reveal.

Summary

The Staggered List system provides a flexible, type-safe API for creating coordinated group animations. By separating timing (Containers) from motion (Items), developers can easily swap animation styles—ranging from standard UI fades to complex cyberpunk glitch and terminal effects—without altering the underlying orchestration logic.
Sources: src/variants/stagger.ts:1-65, src/variants/cyber.ts:1-75