Primitive / Moleculebeta

Stagger List

Reveals child items one after another with configurable stagger and direction using the active animation engine.

Edit on GitHub

pnpm dlx @glinui/cli@latest add stagger-list

1Create your workspace
2Invite your team
3Connect a repository
4Ship your first release

Installation

Install from

pnpm dlx @glinui/cli@latest add stagger-list

Prefer the package?

Usage

Motion engine

Design tokens
Primitives
Blocks

// pnpm add motion (separate dependency, optional)
// Once at your app entry:
import "@glinui/motion/register/motion"


import { StaggerList } from "@glinui/ui"


export function Demo() {
  return (
    <StaggerList engine="motion" as="ul" step={80} className="space-y-2">
      <li>Design tokens</li>
      <li>Primitives</li>
      <li>Blocks</li>
    </StaggerList>
  )
}

GSAP engine

Design tokens
Primitives
Blocks

// pnpm add gsap (separate dependency under GreenSock's own license, not bundled by GLINUI)
// Once at your app entry:
import "@glinui/motion/register/gsap"


import { StaggerList } from "@glinui/ui"


export function Demo() {
  return (
    <StaggerList engine="gsap" as="ul" step={80} className="space-y-2">
      <li>Design tokens</li>
      <li>Primitives</li>
      <li>Blocks</li>
    </StaggerList>
  )
}

Static (animations off)

Design tokens
Primitives
Blocks

import { StaggerList } from "@glinui/ui"


export function Demo() {
  return (
    <StaggerList motion="none" as="ul" step={80} className="space-y-2">
      <li>Design tokens</li>
      <li>Primitives</li>
      <li>Blocks</li>
    </StaggerList>
  )
}

Accessibility

Content is in the DOM and visible to assistive tech before and after the animation.
Animation never gates meaning: the static state is identical to the final animated state.
List semantics are preserved: render with as="ul" and li children.

Reduced Motion

Under prefers-reduced-motion the engine drops travel, blur and scale and only fades opacity. motion="none" renders the final state immediately and never loads an animation library.

Affected properties

opacitytransformfilter

API Reference

Prop	Type	Required	Default	Description
`as`	`StaggerListTag`	No	`"div"`	Element to render.
`step`	`number`	No	`60`	Delay between children in ms.
`order`	`StaggerDirection`	No	`"forward"`	Order children appear in.
`variant / direction / distance`	`see Reveal`	-	`-`	Treatment applied to each child.
`duration / delay / spring / once / threshold / immediate`	`see Reveal`	-	`-`	Same behavior as Reveal.
`engine`	`EngineName`	No	`"css"`	Animation engine. css is built in with zero dependencies; motion and gsap are opt-in (import "@glinui/motion/register/<name>" and install the package). Falls back to MotionEngineProvider, then data-glin-engine on <html>, then css.
`motion`	`MotionLevel`	No	`"system"`	none renders the final state with no animation, subtle animates opacity only, system follows prefers-reduced-motion.
`children`	`React.ReactNode`	No	`-`	Auto-generated from TypeScript source.
`delay`	`number`	No	`-`	Auto-generated from TypeScript source.
`direction`	`RevealDirection`	No	`-`	Auto-generated from TypeScript source.
`distance`	`number`	No	`-`	Auto-generated from TypeScript source.
`duration`	`number`	No	`-`	Auto-generated from TypeScript source.
`immediate`	`boolean`	No	`false`	Auto-generated from TypeScript source.
`once`	`boolean`	No	`true`	Auto-generated from TypeScript source.
`spring`	`SpringInput`	No	`-`	Auto-generated from TypeScript source.
`threshold`	`number`	No	`-`	Auto-generated from TypeScript source.
`variant`	`RevealVariant`	No	`"slide"`	Auto-generated from TypeScript source.

Source

Import directly from the package or browse the source on GitHub. Click any file to view it.

Import

import { StaggerList } from "@glinui/ui"

Source Files

stagger-list.tsx motion-engine.tsx

Dependencies

@glinui/ui@glinui/motion

Generated API Snapshot

Beta

Auto-extracted from TypeScript source in packages/ui/src/components/stagger-list.tsx. This section is in beta and may lag behind hand-curated docs. Regenerate with pnpm --filter @glinui/docs api:generate.

Generated: 2026-10-08T01:41:21.546Z · Full index: /docs/api-metadata

Primary Props Type

StaggerListProps

`StaggerListProps`

Prop	Type	Required	Default	Description
`as`	`StaggerListTag`	No	`"div"`	-
`children`	`React.ReactNode`	No	`-`	-
`delay`	`number`	No	`-`	-
`direction`	`RevealDirection`	No	`-`	-
`distance`	`number`	No	`-`	-
`duration`	`number`	No	`-`	-
`engine`	`EngineName`	No	`-`	Engine override: `css` (default), `motion`, `gsap` or a registered custom engine.
`immediate`	`boolean`	No	`false`	-
`motion`	`MotionLevel`	No	`-`	Motion override. `none` renders the static final state, `subtle` is opacity only.
`once`	`boolean`	No	`true`	-
`order`	`StaggerDirection`	No	`"forward"`	Order the children appear in. Default `forward`.
`spring`	`SpringInput`	No	`-`	-
`step`	`number`	No	`60`	Delay between children in ms. Default 60.
`threshold`	`number`	No	`-`	-
`variant`	`RevealVariant`	No	`"slide"`	-