Animated List

A feed that reveals its children one at a time, newest on top, each entry springing in from `scale: 0`. One more appears every `delay` ms (1000 by default) until the list is full, then it stops — or restarts, with `loop`.

decorativeclientuiv1.2.0

Animated List — live rendermagicui-animatedlist--default ↗

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL

npx shadcn@latest add https://ds.interlace.tools/r/animated-list.json

With the @interlace alias

npx shadcn@latest add @interlace/animated-list

Behavior

What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.

Measured contrast

packages/ui/__tests__/theme-contract-lock.test.ts ↗

Every semantic colour pair this component's own source uses, measured against the shipped hexes in all 4 theme × scheme combinations. The tightest is foreground on background at 16.19:1 (harbor · dark), against a floor of 4.5:1.

Measured WCAG contrast ratios per token pair and theme
Pair	interlacelight	interlacedark	harborlight	harbordark	Floor
foreground on backgroundbody copy	19.65:1	16.97:1	17.74:1	16.19:1	4.5:1SC 1.4.3

Text pairs are held to 4.5:1 (WCAG 2.2 SC 1.4.3); borders, rings and chart axes to 3:1 (SC 1.4.11 non-text). Bold is the worst cell in the row — the one a brand fork has to keep an eye on.

Runtime contract

packages/ui/vitest.config.ts ↗

Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.

Render boundary: 'use client'
Hydrates. It brings JavaScript to any route that imports it — put the boundary here, not at the page.
Minimum viewport: none declared
No width floor: it takes the width it is given. Its container owns the layout question.
Coverage gate: not in the gate
The 100% gate currently covers src/charts/**/*.{ts,tsx} and src/lib/**/*.{ts,tsx} and src/primitives/{button-variants,data-state-model,meter-scale,skeleton-variants}.ts and src/primitives/{alert,aspect-ratio,avatar,badge,box,breadcrumb,button,callout,card,checkbox,container,data-state,focus-ring,grade-badge,grid,input,label,meter,pagination,published-date,reading-time,section,section-boundary,separator,skip-link,stack,stat-strip,tag,textarea,typography,visually-hidden}.tsx. This file is outside it — the glob widens in phase 7.2.

History

This component is at v1.2.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

No release note names this component yet. It shipped with the release above and has not changed since — see the full changelog for what moved elsewhere in the DS.

Import

2 named exports — pull the parts you need.

Public API

import { AnimatedList, AnimatedListItem } from '@/components/ui/magicui/animated-list';

Anatomy

Extracted from the primitive's JSDoc header. The source is the only documentation that can't drift.

div.relative
    ├─ div                         (data-slot="animated-list", aria-live=polite)
    │   └─ AnimatedListItem ×      (data-slot="animated-list-item", motion.div)
    └─ button                      (data-slot="animated-list-pause", aria-pressed)

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

AnimatedListItemProps

Prop	Type	Description
children*	ReactNode	The single feed entry to animate in. Slot it as a `ReactNode` so consumers compose their own card/row/toast without this component owning the shape.
transition	Transition	Spring transition applied to the pop-in. Override to retune the physics (e.g. softer damping for large cards). @default { type: "spring", stiffness: 350, damping: 40 }

AnimatedListProps

Prop	Type	Description
children*	ReactNode	The feed entries to reveal in sequence. Each child should carry a stable `key`; the list animates entries in one-at-a-time, newest first.
delay	number	Milliseconds between each entry being revealed. @default 1000
loop	boolean	Restart the reveal from the first entry once the last one has appeared, producing a continuous loop. When `false`, the list settles on the full set and stops. @default false
transition	Transition	Spring transition for each entry's pop-in. Forwarded to every {@link AnimatedListItem}. @default { type: "spring", stiffness: 350, damping: 40 }
pauseOnHover	boolean	Pause the reveal while the pointer is over the list. Pairs with the keyboard-reachable pause control for full WCAG 2.2.2 coverage. @default false
showPauseControl	boolean	Render a visible play/pause button (WCAG 2.2.2 — Pause, Stop, Hide for auto-updating content that runs longer than 5s). Turn off only when an enclosing surface exposes its own pause control. @default true
pauseLabel	string	Accessible label for the pause control. Customize per context (e.g. "Pause activity feed"). @default "Pause animated feed"

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour: Native element semantics — no interaction layer to get wrong.
Focus ring (WCAG 2.2 SC 2.4.13): Inherited from the preflight focus contract shipped in @interlace/theme.
Reduced motion: Animation is gated on prefers-reduced-motion.
ARIA in the source: aria-hidden
aria-label
aria-live
aria-pressed

Examples

2 more states from the same story file.

pause on hovermagicui-animatedlist--pause-on-hover ↗

fast revealmagicui-animatedlist--fast-reveal ↗

Dependencies

Base UI primitive: Native / no Base UI dependency
Lucide icons: Pause
Play
NPM dependencies: lucide-react
motion
Registry dependencies: @interlace/theme
@interlace/cn
@interlace/use-reduced-motion

Source

The full implementation — components/ui/magicui/animated-list.tsx once installed.

306 lines · TypeScript

github ↗

"use client";

import {
  Children,
  forwardRef,
  useEffect,
  useMemo,
  useState,
  type ComponentPropsWithoutRef,
  type ReactElement,
  type ReactNode,
} from "react";

// @interlace/animated-list v1.2.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/animated-list
// What changed since: https://ds.interlace.tools/c/animated-list#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — AnimatedList + AnimatedListItem

…286 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/animated-list.json