Steps rise in one after another, a running title has a light passing through it, a finished step's tick pops in and draws itself, and a row opens to its real height with its detail cascading in.
See it as an AI agent does.See this component the way an AI agent does.
Installation
npx shadcn@latest add @keyframery/traceThis adds components/keyframery/trace.tsx and its primitive to your project, and installs UI SDK, along with agent-content, collapsible, which it builds on. The motion tokens are added to your global CSS the first time you install a component.
Usage
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/keyframery/trace"
export default function Usage() {
return (
<Trace>
<TraceLine>
<TraceIcon />
<TraceTitle>Read the order history</TraceTitle>
</TraceLine>
<TraceLine status="running">
<TraceIcon />
<TraceTitle>Drafting the refund email</TraceTitle>
</TraceLine>
</Trace>
)
}Anatomy
How the parts fit together:
Trace
└── TraceLine
├── TraceIcon
└── TraceTitleExamples
Status
status on a line is "running", "error" or "pending"; leave it out once the step is done. With no children, the icon follows it: a spinner, a mark, a dashed ring, or a tick that draws itself.
A row that expands
Wrap a line in TraceCollapsibleTrigger inside TraceCollapsible. The detail opens to its real height and its paragraphs rise in one after another.
Your own icons
Put an icon inside TraceIcon to name the action instead of showing the status. The title stays the line's name for screen readers.
Motion
| Move | What you see |
|---|---|
| Cascade | Lines rise in one after another as they arrive. |
| Fade | A running title has a soft light passing through it; it stops for reduced motion. |
| Draw | When a step finishes, its tick pops in and draws itself. |
| Height | A row that expands opens to its real height. |
| Cascade | The detail's paragraphs rise in one after another as it opens. |
| Spring | The chevron turns down on a spring. |
Timing and springiness follow the motion style you set. To change how fast this trace moves, pass speed:
<Trace speed="fast">
…
</Trace>"fast" is 0.6×, "slow" 1.4×, and a number sets the multiplier. With reduced motion turned on, nothing moves: changes happen at once or with a short fade.
Theming
Set these CSS variables on the component or a parent. Leave them unset to follow the light and dark theme. The open Customize panel below the preview lets you try these settings.
| Variable | What it changes | Default |
|---|---|---|
--trace-ink | Step text | text-muted-foreground |
--trace-error | Failed step | text-destructive |
--trace-font | Step size | text-[13px] |
--trace-detail-font | Detail size | text-[12.5px] |
--trace-gap | Step spacing | gap-2.5 |
--trace-icon-size | Status icon size | size-4 |
--trace-indent | Detail indent | ps-4 |
API reference
Every part takes className and children, along with the props of the element it renders. The parts are rendered by UI SDK, so they also take render, to draw your own element, and a function of their state for className and style.
Trace
Renders a <div>, and takes its props too.
Prop
Type
TraceLine
Renders a <span>, and takes its props too.
Prop
Type
TraceCollapsible
Renders a <div>, and takes its props too.
Prop
Type
TraceCollapsibleContent
Renders a <div>, and takes its props too.
Prop
Type
Other parts
These take the props of the element they render, and nothing else:
TraceIcon: a<span>TraceTitle: a<span>TraceCollapsibleTrigger: a<button>TraceDescription: a<span>
Keyboard
| Key | What it does |
|---|---|
| Tab | Moves to the next row that expands, or link. |
| Enter or Space | Opens or closes the focused row. |
Accessibility
Roles, keyboard and focus are declared on the component's UI SDK primitive, and state is announced through the matching ARIA attributes. More in Accessibility.
Built on UI SDK's core
UI SDK doesn't ship a trace, so this one is defined with its core: one definePrimitive in components/keyframery/core/trace-core.ts, with no React in it. UI SDK's adapters can render that same definition in Vue, Svelte, Solid and web components. To keep your own styling and take only the motion, import from @/components/keyframery/primitives/trace.
Questions
How does the animated Trace for UI SDK move?
Cascade: Lines rise in one after another as they arrive. Fade: A running title has a soft light passing through it; it stops for reduced motion. Draw: When a step finishes, its tick pops in and draws itself. Height: A row that expands opens to its real height. Cascade: The detail's paragraphs rise in one after another as it opens. Spring: The chevron turns down on a spring.
Do I need Motion or Framer Motion for the animated Trace?
No. Every move is plain CSS, so there is nothing to install besides the component and UI SDK.
UI SDK has no trace. How is this one built on UI SDK?
Its behaviour is one definition written with UI SDK's core (definePrimitive), in components/keyframery/core/trace-core.ts. Its parts are rendered by UI SDK's adapter, so they take render, state-based class names and data-slot, like every UI SDK component.
What happens to the Trace when someone turns on reduced motion?
Nothing moves. State changes happen at once, or with a short fade.
More in Chat
All componentsMessage Scroller
A conversation scroller that follows new messages, preserves reading position and counts unread messages, composed from UI SDK scroll area and core.
Animations not working
Why a UI SDK component won't animate, jumps, or vanishes without its exit: the nine causes we see most, each with a tested fix.