Keyframery

Stepper

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.

Resize preview. Focus the handle and use the left or right arrow keys. Hold Shift for larger steps.— px
Customize1 controls
Animation speed1×

Installation

npx shadcn@latest add @keyframery/stepper

This 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

MoveWhat you see
DrawThe connector to the next step fills from its start once that step is reached, and empties when you go back.
DrawA finished step's number shrinks into a blur and a check draws itself in its place.
PopThe current step's indicator grows a touch and takes its ring.
DirectionA step's panel arrives 32px from the side you moved toward, with 6px of blur, on a spring (from below or above when vertical).
PressA 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.

VariableWhat it changesDefault
--stepper-accentFinished and current steps, and the filled line--primary
--stepper-trackThe line before it fills, and upcoming steps' rim--border
--stepper-inkTitles of reached steps--foreground
--stepper-mutedUpcoming titles, numbers and descriptions--muted-foreground
--stepper-errorA step in error--destructive
--stepper-sizeThe indicators' diameter1.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

KeyWhat it does
TabMoves into the steps as one tab stop, on the current step.
ArrowRight / ArrowLeftMoves between steps (ArrowDown and ArrowUp when vertical).
Home / EndMoves to the first or last step.
Enter / SpaceGoes 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.

All components

On this page