aa-stagger

aa-stagger adds time between sibling animations — either children of an animated parent (e.g. aa-animate="fade-up" + aa-stagger="0.1") or split-text units inside a text-* animation. The first numeric token is the unit time in seconds; flags after it change origin, randomize the order, or treat the elements as a 2D grid.

If you omit aa-stagger, the unit defaults to a value chosen by the resolved split mode — chars cascades faster than words, which cascades faster than lines. The defaults are configurable on init:

init({
  stagger: {
    chars: 0.02,    // per char
    words: 0.05,    // per word
    lines: 0.1,     // per line (or per group when line-grouped)
    default: 0.1,   // aa-children with no aa-split
  },
})

Modes

aa-stagger is a single attribute carrying a unit time plus optional space-separated flags.

Token	Effect
`0.1`	unit stagger in seconds (required)
`start`	fire from the first element (default)
`center`	fire from the middle outward
`end`	fire from the last element backwards
`edges`	fire from both ends towards the middle
`random`	every element gets a random delay
`random:N`	shuffle into batches of `N` — `N` scattered elements share each delay
`grid`	treat elements as a 2D grid (auto-detected from layout)

Combine flags with spaces: aa-stagger="0.1 center grid". Random ignores origin and grid — if both are present, random wins.

For text animations, a second number sets the per-line offset in line-grouped modes (aa-split="lines-chars" / "lines-words"): aa-stagger="0.02 0.2" staggers chars 0.02s apart and lines 0.2s apart. Flags only apply to the unit stagger (chars/words), not to the line cascade.

Required GSAP plugins

gsap. SplitText is needed when staggering across split-text units.

Live demo — origin (1D)

Sequential stagger across 25 squares. The unit stagger flows in DOM order; the origin flag controls where the wave starts.

aa-stagger="0.05" — default (start)

aa-stagger="0.05 center"

aa-stagger="0.05 end"

aa-stagger="0.05 edges"

Live demo — random and grouped random

random shuffles every element. random:N reveals N scattered elements per beat — every element gets a random rank and elements with ranks 0..N-1 fire first, then N..2N-1, and so on. The batches are random subsets, not adjacent runs.

aa-stagger="0.05 random"

aa-stagger="0.1 random:5" — 5 random squares per beat

Live demo — grid (2D)

Add grid to treat the elements as a 2D layout. GSAP measures each element’s screen position so distance is geometric, not DOM-order — exactly what you want for blog cards, image grids, or any wrapping flex/grid layout.

aa-stagger="0.08 grid" — start corner — diagonal wave

aa-stagger="0.08 center grid" — ripple from the middle

aa-stagger="0.08 edges grid" — corners collapse inward

aa-stagger="0.08 end grid" — from the bottom-right corner

Live demo — text

random:N is most useful on character-split text — five scattered chars light up per beat for a sparkle/decode effect. Add a second number to cascade lines: chars stagger within each line, lines fall in order.

aa-stagger=“0.02 random”

A three-line headline that fades in with each character revealed in random order across the entire heading.

aa-stagger=“0.02 random:5”

A three-line headline that fades in five scattered characters per beat — a decode-style reveal.

aa-stagger=“0.04 0.3 random:4” aa-split=“lines-chars”

A three-line headline where four scattered chars reveal per beat within each line, and the lines themselves cascade top to bottom.

aa-stagger=“0.04 center”