Steps that are complete, current, upcoming or in error, horizontal or vertical, as a read-only progress strip (an order) or the buttons of a multi-step form, linear or not. The line between steps draws itself up to the current one, a finished step's number gives way to a check that draws itself, and panels arrive from the side you moved toward.
See it as an AI agent does.See this component the way an AI agent does.
Installation
npx shadcn@latest add @keyframery/stepperThis adds components/keyframery/stepper.tsx and its primitive to your project, and installs UI SDK. The motion tokens are added to your global CSS the first time you install a component.
Usage
import { Stepper, StepperList } from "@/components/keyframery/stepper"
export default function Usage() {
return (
<Stepper
aria-label="Order progress"
interactive={false}
value="packed"
steps={[
{ value: "placed", label: "Placed" },
{ value: "packed", label: "Packed" },
{ value: "shipped", label: "Shipped" },
]}
>
<StepperList />
</Stepper>
)
}Examples
A read-only progress strip
With interactive={false} the steps are text, not buttons, and the current one carries aria-current="step". Pass every value to completed for a finished order.
A multi-step form
Linear by default: Continue moves on, and the step buttons go back to any step already reached. Panels arrive from the side you moved toward.
Vertical, non-linear, with an error
orientation="vertical" hangs the line under each indicator. linear={false} lets any step be chosen; a step with error shows it wherever it is.
Motion
| Move | What you see |
|---|---|
| Draw | The connector to the next step fills from its start once that step is reached, and empties when you go back. |
| Draw | A finished step's number shrinks into a blur and a check draws itself in its place. |
| Pop | The current step's indicator grows a touch and takes its ring. |
| Direction | A step's panel arrives 32px from the side you moved toward, with 6px of blur, on a spring (from below or above when vertical). |
| Press | A step you can go to sinks a little when pressed. |
Timing and springiness follow the motion style you set. To change how fast this stepper moves, pass speed:
<Stepper speed="fast">
…
</Stepper>"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 |
|---|---|---|
--stepper-accent | Finished and current steps, and the filled line | --primary |
--stepper-track | The line before it fills, and upcoming steps' rim | --border |
--stepper-ink | Titles of reached steps | --foreground |
--stepper-muted | Upcoming titles, numbers and descriptions | --muted-foreground |
--stepper-error | A step in error | --destructive |
--stepper-size | The indicators' diameter | 1.75rem |
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.
Stepper
Renders a <div>, and takes its props too.
Prop
Type
StepperPanel
Renders a <div>, and takes its props too.
Prop
Type
Other parts
These take the props of the element they render, and nothing else:
StepperList: a<ol>StepperConnector: a<span>StepperDescription: a<span>StepperIndicator: a<span>StepperItem: a<li>StepperStep: a<button>StepperTitle: a<span>
Keyboard
| Key | What it does |
|---|---|
| Tab | Moves into the steps as one tab stop, on the current step. |
| ArrowRight / ArrowLeft | Moves between steps (ArrowDown and ArrowUp when vertical). |
| Home / End | Moves to the first or last step. |
| Enter / Space | Goes to the focused step, if it can be reached. |
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 stepper, so this one is defined with its core: one definePrimitive in components/keyframery/core/stepper-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/stepper.
Questions
How does the animated Stepper for UI SDK move?
Draw: The connector to the next step fills from its start once that step is reached, and empties when you go back. Draw: A finished step's number shrinks into a blur and a check draws itself in its place. Pop: The current step's indicator grows a touch and takes its ring. Direction: A step's panel arrives 32px from the side you moved toward, with 6px of blur, on a spring (from below or above when vertical). Press: A step you can go to sinks a little when pressed.
Do I need Motion or Framer Motion for the animated Stepper?
No. Every move is plain CSS, so there is nothing to install besides the component and UI SDK.
UI SDK has no stepper. How is this one built on UI SDK?
Its behaviour is one definition written with UI SDK's core (definePrimitive), in components/keyframery/core/stepper-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 Stepper when someone turns on reduced motion?
Nothing moves. State changes happen at once, or with a short fade.