Core API
stagger
A composition node that plays child animations sequentially with a fixed delay between them.
A stagger node is a composition that plays its child animations in sequence, but with a fixed delay between the start of each one.
Example
import { a } from "@freestylejs/ani-core";
// 1. Define the animation for a single list item.
const itemAnimation = a.ani({ to: { opacity: 1, y: 0 }, duration: 0.5 });
// 2. Create a stagger animation for three items.
// Each subsequent animation will start 0.1s after the previous one.
const listEntrance = a.stagger(
[
itemAnimation, // for item 1
itemAnimation, // for item 2
itemAnimation, // for item 3
],
{ offset: 0.1 }
);
// 3. Create a timeline.
const myTimeline = a.timeline(listEntrance);
// 4. Play the animation.
// Note: The `from` value applies to all three conceptual items.
myTimeline.play({ from: { opacity: 0, y: 20 } });Usage & Concepts
Overview
stagger is a specialized composition node for creating cascading or "domino" effects, typically used for lists of elements. It runs its child animations in order, but delays the start of each subsequent animation by a fixed offset time. It's essentially a sequence with a built-in, regular delay.
Best Practices
- Do use
staggerfor animating lists of items into or out of view. - Don't use
staggerif you need variable delays between animations; build a customsequencewithdelaynodes instead.
API Reference
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
children | AnimationNode<G>[] | An array of animation nodes to play. | — |
props | StaggerNodeProps | An object containing the stagger configuration. | — |
id | AnimationId | (Optional) A unique identifier for the animation node. | undefined |
Type Definitions
interface StaggerNodeProps {
offset: number;
timing?: TimingFunction | TimingFunction[];
};
function stagger<G>(
children: AnimationNode<G>[],
props: StaggerNodeProps,
id?: AnimationId
): AnimationNode<G>;