# Animated Stepper for UI SDK (/docs/components/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.

<ComponentPreview slug="stepper" source="{&#x22;code&#x22;:&#x22;\&#x22;use client\&#x22;\n\nimport * as React from \&#x22;react\&#x22;\n\nimport { Button } from \&#x22;@/components/keyframery/button\&#x22;\nimport { Field, FieldLabel } from \&#x22;@/components/keyframery/field\&#x22;\nimport { Input } from \&#x22;@/components/keyframery/input\&#x22;\nimport { Stepper, StepperList, StepperPanel, type StepperStepData } from \&#x22;@/components/keyframery/stepper\&#x22;\n\nconst order: StepperStepData[] = [\n  { value: \&#x22;placed\&#x22;, label: \&#x22;Placed\&#x22;, description: \&#x22;18 Nov\&#x22; },\n  { value: \&#x22;paid\&#x22;, label: \&#x22;Paid\&#x22;, description: \&#x22;18 Nov\&#x22; },\n  { value: \&#x22;packed\&#x22;, label: \&#x22;Packed\&#x22;, description: \&#x22;19 Nov\&#x22; },\n  { value: \&#x22;shipped\&#x22;, label: \&#x22;Shipped\&#x22; },\n  { value: \&#x22;delivered\&#x22;, label: \&#x22;Delivered\&#x22; },\n]\n\nconst checkout = [\n  { value: \&#x22;contact\&#x22;, label: \&#x22;Contact\&#x22;, description: \&#x22;Email and phone\&#x22; },\n  { value: \&#x22;shipping\&#x22;, label: \&#x22;Shipping\&#x22;, description: \&#x22;Address and speed\&#x22; },\n  { value: \&#x22;payment\&#x22;, label: \&#x22;Payment\&#x22;, description: \&#x22;Card details\&#x22; },\n  { value: \&#x22;review\&#x22;, label: \&#x22;Review\&#x22;, description: \&#x22;Place the order\&#x22; },\n]\n\nexport default function StepperDemo({\n  orientation = \&#x22;horizontal\&#x22;,\n  linear = true,\n  interactive = true,\n  strip = true,\n  descriptions = true,\n  error = \&#x22;none\&#x22;,\n  start = \&#x22;packed\&#x22;,\n  size = 28,\n  gap = 24,\n  accent = \&#x22;\&#x22;,\n  track = \&#x22;\&#x22;,\n  errorColor = \&#x22;\&#x22;,\n}: {\n  orientation?: \&#x22;horizontal\&#x22; | \&#x22;vertical\&#x22;\n  linear?: boolean\n  interactive?: boolean\n  strip?: boolean\n  descriptions?: boolean\n  error?: \&#x22;none\&#x22; | \&#x22;shipping\&#x22; | \&#x22;payment\&#x22;\n  start?: \&#x22;placed\&#x22; | \&#x22;paid\&#x22; | \&#x22;packed\&#x22; | \&#x22;shipped\&#x22; | \&#x22;delivered\&#x22;\n  size?: number\n  gap?: number\n  accent?: string\n  track?: string\n  errorColor?: string\n}) {\n  const [step, setStep] = React.useState(\&#x22;contact\&#x22;)\n  const index = checkout.findIndex((s) => s.value === step)\n  const steps = checkout.map((s) => ({ ...s, description: descriptions ? s.description : undefined, error: s.value === error }))\n\n  const style = {\n    \&#x22;--stepper-size\&#x22;: `${size}px`,\n    ...(accent ? { \&#x22;--stepper-accent\&#x22;: accent } : null),\n    ...(track ? { \&#x22;--stepper-track\&#x22;: track } : null),\n    ...(errorColor ? { \&#x22;--stepper-error\&#x22;: errorColor } : null),\n  } as React.CSSProperties\n\n  return (\n    <div style={style} className=\&#x22;flex w-full max-w-[600px] flex-col gap-4\&#x22;>\n      {strip && (\n        <div className=\&#x22;rounded-[16px] bg-background px-5 py-4 shadow-[0_0_0_1px_rgb(0_0_0/0.06),0_1px_2px_rgb(0_0_0/0.04)] dark:bg-card dark:shadow-[0_0_0_1px_rgb(255_255_255/0.07)]\&#x22;>\n          <div className=\&#x22;mb-3 flex items-baseline justify-between text-[12px] text-muted-foreground\&#x22;>\n            <span className=\&#x22;font-medium text-foreground\&#x22;>Order #1048</span>\n            <span>Arrives Fri 21 Nov</span>\n          </div>\n          <Stepper\n            aria-label=\&#x22;Order progress\&#x22;\n            interactive={false}\n            steps={order.map((s) => ({ ...s, description: descriptions ? s.description : undefined }))}\n            value={start}\n            completed={start === \&#x22;delivered\&#x22; ? order.map((s) => s.value) : undefined}\n          >\n            <StepperList />\n          </Stepper>\n        </div>\n      )}\n      <div\n        data-demo=\&#x22;checkout\&#x22;\n        className=\&#x22;rounded-[16px] bg-background p-5 shadow-[0_0_0_1px_rgb(0_0_0/0.06),0_1px_2px_rgb(0_0_0/0.04),0_8px_24px_-12px_rgb(0_0_0/0.12)] dark:bg-card dark:shadow-[0_0_0_1px_rgb(255_255_255/0.07)]\&#x22;\n      >\n        <Stepper\n          aria-label=\&#x22;Checkout\&#x22;\n          steps={steps}\n          value={step}\n          onValueChange={setStep}\n          linear={linear}\n          interactive={interactive}\n          orientation={orientation}\n          style={{ gap }}\n        >\n          <StepperList />\n          <div className=\&#x22;grid min-w-0 *:[grid-area:1/1]\&#x22;>\n            <StepperPanel value=\&#x22;contact\&#x22; className=\&#x22;flex flex-col gap-3\&#x22;>\n              <Field name=\&#x22;email\&#x22;>\n                <FieldLabel>Email</FieldLabel>\n                <Input type=\&#x22;email\&#x22; defaultValue=\&#x22;maya.okafor@northwind-studio.com\&#x22; />\n              </Field>\n            </StepperPanel>\n            <StepperPanel value=\&#x22;shipping\&#x22; className=\&#x22;flex flex-col gap-3\&#x22;>\n              <Field name=\&#x22;address\&#x22;>\n                <FieldLabel>Address</FieldLabel>\n                <Input defaultValue=\&#x22;18 Clerkenwell Close, London EC1R 0AA\&#x22; />\n              </Field>\n            </StepperPanel>\n            <StepperPanel value=\&#x22;payment\&#x22; className=\&#x22;flex flex-col gap-3\&#x22;>\n              <Field name=\&#x22;card\&#x22;>\n                <FieldLabel>Card number</FieldLabel>\n                <Input inputMode=\&#x22;numeric\&#x22; defaultValue=\&#x22;4242 4242 4242 4242\&#x22; />\n              </Field>\n            </StepperPanel>\n            <StepperPanel value=\&#x22;review\&#x22; className=\&#x22;flex flex-col gap-1 text-[13px]\&#x22;>\n              <div className=\&#x22;font-medium\&#x22;>3 items · $184.00</div>\n              <div className=\&#x22;text-muted-foreground\&#x22;>Ships to London by Royal Mail, arrives Friday.</div>\n            </StepperPanel>\n          </div>\n          <div className=\&#x22;flex items-center justify-between gap-3 border-t border-border pt-4\&#x22;>\n            <Button variant=\&#x22;ghost\&#x22; data-stepper-action=\&#x22;back\&#x22; disabled={index === 0} onClick={() => setStep(checkout[Math.max(0, index - 1)].value)}>\n              Back\n            </Button>\n            <Button\n              variant=\&#x22;primary\&#x22;\n              data-stepper-action=\&#x22;next\&#x22;\n              onClick={() => setStep(checkout[(index + 1) % checkout.length].value)}\n            >\n              {index === checkout.length - 1 ? \&#x22;Start over\&#x22; : \&#x22;Continue\&#x22;}\n            </Button>\n          </div>\n        </Stepper>\n      </div>\n    </div>\n  )\n}&#x22;,&#x22;bindings&#x22;:{&#x22;orientation&#x22;:[1012,1024],&#x22;linear&#x22;:[1037,1041],&#x22;interactive&#x22;:[1059,1063],&#x22;strip&#x22;:[1075,1079],&#x22;descriptions&#x22;:[1098,1102],&#x22;error&#x22;:[1114,1120],&#x22;start&#x22;:[1132,1140],&#x22;size&#x22;:[1151,1153],&#x22;gap&#x22;:[1163,1165],&#x22;accent&#x22;:[1178,1180],&#x22;track&#x22;:[1192,1194],&#x22;errorColor&#x22;:[1211,1213]},&#x22;root&#x22;:[2055,5397],&#x22;importOffset&#x22;:328}" />

## Installation [#installation]

**CLI**

```bash
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.

**Manual**

**Install the dependencies**

```bash
npm install @ui-sdk/core@0.1.0-beta.9 @ui-sdk/react@0.1.0-beta.9 clsx tailwind-merge
```

**Add the motion tokens**

Copy the [motion tokens](/docs/installation#what-the-cli-adds-to-your-css) into your global CSS, and this file into `lib/keyframery.tsx`. Every component shares them.

**lib/keyframery.tsx**

```tsx
"use client"

/* Speed for Keyframery components, as a prop.

   Every duration in the components is written as calc(Nms * var(--kf-speed, 1)). These helpers set
   that variable for you, so nobody has to know it exists:

     <Tabs speed="fast">                      one component
     <KeyframeryProvider speed="slow">        the whole app

   Parts that render in a portal (popups, menus, dialogs) are not inside the component in the page,
   so they pick the speed up through React context instead of the CSS cascade. */

import * as React from "react"

/** `"fast"` (0.6×), `"normal"` (1×), `"slow"` (1.4×), or any multiplier: `0.8` is 20% quicker. */
export type Speed = "fast" | "normal" | "slow" | number

export type SpeedProps = {
  /** How fast the component moves. `"fast"` (0.6×), `"normal"` (1×), `"slow"` (1.4×), or a multiplier like `0.8`. Popups follow it too. */
  speed?: Speed
}

export type MotionStyleName = "springy" | "calm" | "snappy" | "playful"

const presets = { fast: 0.6, normal: 1, slow: 1.4 } as const

export function speedValue(speed: Speed | undefined): number | undefined {
  if (speed === undefined) return undefined
  return typeof speed === "number" ? speed : presets[speed]
}

const SpeedContext = React.createContext<number | undefined>(undefined)

type SpeedStyle = React.CSSProperties & { "--kf-speed"?: number }

/* Wraps a component's parts. Without `speed` it adds nothing to the page. With it, a
   `display: contents` element carries the variable to the parts in place, and context carries it
   to the parts in a portal. */
export function Speed({ speed, children }: SpeedProps & { children?: React.ReactNode }) {
  const value = speedValue(speed)
  if (value === undefined) return children
  const style: SpeedStyle = { display: "contents", "--kf-speed": value }
  return (
    <SpeedContext value={value}>
      <span data-slot="speed" style={style}>
        {children}
      </span>
    </SpeedContext>
  )
}

/* For parts that render in a portal: adds the speed of the component they belong to. `style` can
   be an object or UI SDK's function of the part's state. */
export function useSpeedStyle<S>(style: S): S {
  return withSpeed(style, React.useContext(SpeedContext))
}

/* Adds a speed to a part's own `style`, for a part that takes `speed` and renders in a portal. */
export function withSpeed<S>(style: S, speed: Speed | undefined): S {
  const value = speedValue(speed)
  if (value === undefined) return style
  if (typeof style === "function")
    return ((state: unknown) => ({ "--kf-speed": value, ...(style as (s: unknown) => React.CSSProperties)(state) })) as S
  return { "--kf-speed": value, ...(style as React.CSSProperties | undefined) } as S
}

/* UI SDK parts take `children` as content or as a function of the part's state. A styled part
   that adds elements of its own (a chevron, a moving key) wraps either form with this, so the
   function form keeps working. */
export function mapChildren<State>(
  children: React.ReactNode | ((state: State) => React.ReactNode),
  wrap: (content: React.ReactNode) => React.ReactNode,
): React.ReactNode | ((state: State) => React.ReactNode) {
  return typeof children === "function" ? (state: State) => wrap(children(state)) : wrap(children)
}

/* Sets speed and motion style for the whole app, popups included. A component's own `speed` prop
   still wins inside that component. Server-rendered pages can put `data-motion` on <html> directly
   to avoid a change after hydration. */
export function KeyframeryProvider({
  speed,
  motion,
  children,
}: SpeedProps & {
  /** The motion style for the whole app: `"springy"` (the default), `"calm"`, `"snappy"` or `"playful"`. */
  motion?: MotionStyleName
  children?: React.ReactNode
}) {
  const value = speedValue(speed)
  React.useLayoutEffect(() => {
    const html = document.documentElement
    if (motion) html.setAttribute("data-motion", motion)
    if (value !== undefined) html.style.setProperty("--kf-speed", String(value))
    return () => {
      if (motion) html.removeAttribute("data-motion")
      if (value !== undefined) html.style.removeProperty("--kf-speed")
    }
  }, [motion, value])
  return children
}
```

**Copy the component**

**components/keyframery/stepper.tsx**

```tsx
"use client"

export * from "@/components/keyframery/primitives/stepper"

/* Styled stepper: the animated primitive plus the Keyframery look. Round indicators joined by
   hairline connectors that fill in the accent as steps are reached; the current step's indicator is
   a key ringed in the accent, a finished one is filled with a drawn check, an error one turns the
   destructive colour with a mark. Below 28rem wide (a container query) a horizontal stepper keeps
   only the current step's title.

   Theming: set these CSS variables on the stepper or anything around it. Each falls back to the
   theme's own token, so nothing changes until you set one.
     --stepper-accent   finished and current steps, and the filled connector  (default: --primary)
     --stepper-track    the connector before it fills, and upcoming steps' rim  (default: --border)
     --stepper-ink      titles of reached steps                               (default: --foreground)
     --stepper-muted    upcoming titles, numbers and descriptions             (default: --muted-foreground)
     --stepper-error    a step in error                                       (default: --destructive)
     --stepper-size     the indicators' diameter                              (default: 1.75rem) */

import * as React from "react"

import {
  Stepper as StepperPrimitive,
  StepperConnector as StepperConnectorPrimitive,
  StepperDescription as StepperDescriptionPrimitive,
  StepperIndicator as StepperIndicatorPrimitive,
  StepperItem as StepperItemPrimitive,
  StepperList as StepperListPrimitive,
  StepperPanel as StepperPanelPrimitive,
  StepperStep as StepperStepPrimitive,
  StepperTitle as StepperTitlePrimitive,
} from "@/components/keyframery/primitives/stepper"
import { Speed, type SpeedProps } from "@/lib/keyframery"
import { cn } from "@/lib/utils"

/* UI SDK parts take a class name or a function of the part's state. Keep both working. */
function withClass<S>(base: string, className: string | ((state: S) => string | undefined) | undefined) {
  return typeof className === "function" ? (state: S) => cn(base, className(state)) : cn(base, className)
}

function Stepper({ speed, className, ...props }: React.ComponentProps<typeof StepperPrimitive> & SpeedProps) {
  return (
    <Speed speed={speed}>
      <StepperPrimitive className={withClass("group/stepper @container/stepper flex w-full min-w-0 flex-col gap-6", className)} {...props} />
    </Speed>
  )
}

function StepperItem({ className, ...props }: React.ComponentProps<typeof StepperItemPrimitive>) {
  return (
    <StepperItemPrimitive
      className={withClass(
        cn(
          "group/item relative flex min-w-0",
          /* Horizontal: equal columns; the indicator on top with the line running from it to the next
             step, the words underneath. */
          "data-[orientation=horizontal]:flex-1 data-[orientation=horizontal]:flex-col data-[orientation=horizontal]:pr-3 data-[orientation=horizontal]:data-last:w-max data-[orientation=horizontal]:data-last:max-w-[40%] data-[orientation=horizontal]:data-last:flex-none data-[orientation=horizontal]:data-last:pr-2",
          /* Vertical: the line hangs under the indicator, down to the next step. */
          "data-[orientation=vertical]:flex-col data-[orientation=vertical]:pb-6 data-[orientation=vertical]:data-last:pb-0",
        ),
        className,
      )}
      {...props}
    />
  )
}

function StepperStep({ className, ...props }: React.ComponentProps<typeof StepperStepPrimitive>) {
  return (
    <StepperStepPrimitive
      className={withClass(
        cn(
          "-m-1 flex min-w-0 shrink-0 items-center gap-3 rounded-[10px] p-1 text-left outline-none select-none",
          "group-data-[orientation=vertical]/item:items-start",
          "group-data-[orientation=horizontal]/item:max-w-full group-data-last/item:max-w-none group-data-[orientation=horizontal]/item:flex-col group-data-[orientation=horizontal]/item:items-start group-data-[orientation=horizontal]/item:gap-2.5",
          "focus-visible:ring-2 focus-visible:ring-ring",
          "data-reachable:cursor-pointer aria-disabled:cursor-default",
          "data-reachable:not-aria-[current=step]:hover:[&_[data-slot=stepper-indicator]]:shadow-[inset_0_0_0_1.5px_var(--stepper-accent,var(--primary))]",
        ),
        className,
      )}
      {...props}
    />
  )
}

function StepperIndicator({ className, ...props }: React.ComponentProps<typeof StepperIndicatorPrimitive>) {
  return (
    <StepperIndicatorPrimitive
      className={withClass(
        cn(
          "size-[var(--stepper-size,1.75rem)] shrink-0 rounded-full text-[12px] leading-none font-medium",
          /* Upcoming: a quiet rim. */
          "bg-background text-[color:var(--stepper-muted,var(--muted-foreground))] shadow-[inset_0_0_0_1px_var(--stepper-track,var(--border))] dark:bg-transparent",
          /* Current: a key ringed in the accent, popping a touch larger. */
          "data-[state=current]:scale-105 data-[state=current]:text-[color:var(--stepper-ink,var(--foreground))] data-[state=current]:shadow-[inset_0_0_0_1.5px_var(--stepper-accent,var(--primary)),0_0_0_4px_color-mix(in_oklab,var(--stepper-accent,var(--primary))_12%,transparent)]",
          /* Complete: filled, with the check. */
          "data-[state=complete]:bg-[var(--stepper-accent,var(--primary))] data-[state=complete]:text-primary-foreground data-[state=complete]:shadow-none",
          /* Error. */
          "data-[state=error]:bg-[color-mix(in_oklab,var(--stepper-error,var(--destructive))_12%,transparent)] data-[state=error]:text-[color:var(--stepper-error,var(--destructive))] data-[state=error]:shadow-[inset_0_0_0_1.5px_var(--stepper-error,var(--destructive))]",
        ),
        className,
      )}
      {...props}
    />
  )
}

function StepperTitle({ className, ...props }: React.ComponentProps<typeof StepperTitlePrimitive>) {
  return (
    <StepperTitlePrimitive
      className={withClass(
        cn(
          "truncate text-[13px] leading-[1.35] font-medium @max-md/stepper:overflow-visible @max-md/stepper:text-clip text-[color:var(--stepper-ink,var(--foreground))] transition-colors duration-[calc(200ms*var(--kf-speed,1))] ease-house motion-reduce:transition-none",
          "group-data-[state=upcoming]/item:text-[color:var(--stepper-muted,var(--muted-foreground))] group-data-[state=error]/item:text-[color:var(--stepper-error,var(--destructive))]",
        ),
        className,
      )}
      {...props}
    />
  )
}

function StepperDescription({ className, ...props }: React.ComponentProps<typeof StepperDescriptionPrimitive>) {
  return (
    <StepperDescriptionPrimitive
      className={withClass("truncate text-[12px] leading-[1.35] text-[color:var(--stepper-muted,var(--muted-foreground))]", className)}
      {...props}
    />
  )
}

function StepperConnector({ className, ...props }: React.ComponentProps<typeof StepperConnectorPrimitive>) {
  return (
    <StepperConnectorPrimitive
      className={withClass(
        cn(
          "rounded-full bg-[var(--stepper-track,var(--border))] after:rounded-full after:bg-[var(--stepper-accent,var(--primary))]",
          "data-[orientation=horizontal]:absolute data-[orientation=horizontal]:top-[calc(var(--stepper-size,1.75rem)/2-0.75px)] data-[orientation=horizontal]:right-[10px] data-[orientation=horizontal]:left-[calc(var(--stepper-size,1.75rem)+10px)] @max-md/stepper:data-[orientation=horizontal]:right-[4px] @max-md/stepper:data-[orientation=horizontal]:left-[calc(var(--stepper-size,1.75rem)+4px)] data-[orientation=horizontal]:h-[1.5px]",
          "data-[orientation=vertical]:absolute data-[orientation=vertical]:top-[calc(var(--stepper-size,1.75rem)+6px)] data-[orientation=vertical]:bottom-[6px] data-[orientation=vertical]:left-[calc(var(--stepper-size,1.75rem)/2-0.75px)] data-[orientation=vertical]:w-[1.5px]",
        ),
        className,
      )}
      {...props}
    />
  )
}

/* The steps from `steps`, with titles and descriptions. Pass children to lay them out yourself. */
function StepperList({ className, children, ...props }: React.ComponentProps<typeof StepperListPrimitive>) {
  return (
    <StepperListPrimitive
      className={withClass(
        cn("flex w-full min-w-0 data-[orientation=horizontal]:items-start data-[orientation=vertical]:flex-col"),
        className,
      )}
      {...props}
    >
      {children ??
        ((state) =>
          state.steps.map((step) => (
            <StepperItem key={step.value} value={step.value}>
              <StepperStep value={step.value}>
                <StepperIndicator value={step.value} />
                <span
                  className={cn(
                    "flex min-w-0 max-w-full flex-col gap-0.5 group-data-last/item:max-w-none",
                    /* Narrow and horizontal: only the current step keeps its words. */
                    "@max-md/stepper:group-data-[orientation=horizontal]/stepper:not-group-data-[state=current]/item:sr-only",
                    "group-data-[orientation=vertical]/item:pt-[calc((var(--stepper-size,1.75rem)-18px)/2)]",
                  )}
                >
                  <StepperTitle>{step.label}</StepperTitle>{" "}
                  {step.description && (
                    <StepperDescription className="@max-md/stepper:group-data-[orientation=horizontal]/stepper:hidden">{step.description}</StepperDescription>
                  )}
                </span>
              </StepperStep>
              <StepperConnector value={step.value} />
            </StepperItem>
          )))}
    </StepperListPrimitive>
  )
}

function StepperPanel({ className, ...props }: React.ComponentProps<typeof StepperPanelPrimitive>) {
  return <StepperPanelPrimitive className={withClass("min-w-0 outline-none", className)} {...props} />
}

export { Stepper, StepperConnector, StepperDescription, StepperIndicator, StepperItem, StepperList, StepperPanel, StepperStep, StepperTitle }
```

**components/keyframery/primitives/stepper.tsx**

```tsx
"use client"

/* Animated stepper, on UI SDK's core. UI SDK ships none, so the behaviour is defined in
   `@/components/core/stepper` with `definePrimitive` and rendered here. This file adds motion only.
   Colours, radii and spacing stay yours.

   - Draw: the connector to the next step fills from its start once that step is reached, so the line
     draws itself up to the current step (and back when someone returns).
   - Draw: a finished step's number gives way to a check that draws itself; the indicator pops.
   - Direction: a step's panel arrives from the side someone moved toward (from the right going on,
     from the left going back; from below and above in a vertical stepper), as the tab panels do. */

import type { StateOf } from "@ui-sdk/core"
import { type PartProps, usePart, usePrimitive } from "@ui-sdk/react/primitive"
import * as React from "react"

import { stepper, type StepperOptions, type StepperStep as StepperStepData } from "@/components/keyframery/core/stepper-core"
import { cn } from "@/lib/utils"

/* UI SDK parts take a class name or a function of the part's state. Keep both working. */
function withClass<S>(base: string, className: string | ((state: S) => string | undefined) | undefined) {
  return typeof className === "function" ? (state: S) => cn(base, className(state)) : cn(base, className)
}

const keyframes = "@keyframes kf-stepper-check{from{stroke-dashoffset:1}}"

type StepperProps = StepperOptions & Omit<PartProps<"div", StateOf<typeof stepper, "root">>, "defaultValue">

/* The stepper. Put a `StepperList` (it renders every step from `steps` unless you give it items) and
   any `StepperPanel`s inside. */
function Stepper({ steps, value, defaultValue, onValueChange, completed, interactive, linear, orientation, ...props }: StepperProps) {
  const handle = usePrimitive(stepper, { steps, value, defaultValue, onValueChange, completed, interactive, linear, orientation })
  const root = usePart(handle, "root", {}, props, "div")
  return (
    <>
      <style href="kf-stepper" precedence="default">
        {keyframes}
      </style>
      {root}
    </>
  )
}

/* The ordered list of steps. Its children can be a function of the steps; without children it
   renders each one bare (indicator, title, description, connector). */
function StepperList({ className, children, ...props }: PartProps<"ol", StateOf<typeof stepper, "list">>) {
  return usePart(
    stepper,
    "list",
    {},
    {
      ...props,
      className,
      children:
        children ??
        ((state) =>
          state.steps.map((step) => (
            <StepperItem key={step.value} value={step.value}>
              <StepperStep value={step.value}>
                <StepperIndicator value={step.value} />
                <span>
                  <StepperTitle>{step.label}</StepperTitle>{" "}
                  {step.description && <StepperDescription>{step.description}</StepperDescription>}
                </span>
              </StepperStep>
              <StepperConnector value={step.value} />
            </StepperItem>
          ))),
    },
    "ol",
  )
}

function StepperItem({ className, ...props }: { value: string } & PartProps<"li", StateOf<typeof stepper, "item">>) {
  return usePart(stepper, "item", { value: props.value }, { ...props, className }, "li")
}

/* The step: a button in an interactive stepper, a span in a progress strip. */
function StepperStep({ value, className, ...props }: { value: string } & PartProps<"button", StateOf<typeof stepper, "step">>) {
  return usePart(
    stepper,
    "step",
    { value },
    {
      ...props,
      className: withClass("transition-[scale] duration-[calc(240ms*var(--kf-speed,1))] ease-pop data-reachable:active:scale-[0.97] motion-reduce:transition-none!", className),
    },
    "button",
  )
}

/* The number, or once finished a check that draws itself. With no children it renders both and lets
   `data-state` choose. */
function StepperIndicator({ value, className, children, ...props }: { value?: string } & PartProps<"span", StateOf<typeof stepper, "indicator">>) {
  return usePart(
    stepper,
    "indicator",
    (value === undefined ? {} : { value }) as { value: string },
    {
      ...props,
      className: withClass(
        cn(
          "relative grid place-items-center *:[grid-area:1/1]",
          "transition-[background-color,color,box-shadow,scale] duration-[calc(420ms*var(--kf-speed,1))] ease-pop",
          "data-[state=current]:animate-none data-[state=complete]:[&_[data-check]]:opacity-100",
          "motion-reduce:transition-none!",
        ),
        className,
      ),
      children:
        children ??
        ((state) => (
          <>
            <span
              className={cn(
                "tabular-nums transition-[opacity,scale,filter] duration-[calc(260ms*var(--kf-speed,1))] ease-house motion-reduce:transition-none!",
                state.state === "complete" || state.state === "error" ? "scale-50 opacity-0 blur-[2px]" : "",
              )}
            >
              {state.index + 1}
            </span>
            {state.state === "complete" && (
              <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden className="size-3.5">
                <path
                  d="M3.5 8.5 6.5 11.5 12.5 4.75"
                  pathLength={1}
                  className="[stroke-dasharray:1] animate-[kf-stepper-check_calc(320ms*var(--kf-speed,1))_var(--ease-house)_calc(120ms*var(--kf-speed,1))_backwards] motion-reduce:animate-none"
                />
              </svg>
            )}
            {state.state === "error" && (
              <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" aria-hidden className="size-3.5">
                <path d="M8 4.5v4.25" />
                <path d="M8 11.5h.01" />
              </svg>
            )}
          </>
        )),
    },
    "span",
  )
}

function StepperTitle({ className, ...props }: PartProps<"span">) {
  return usePart(stepper, "title", {}, { ...props, className }, "span")
}

function StepperDescription({ className, ...props }: PartProps<"span">) {
  return usePart(stepper, "description", {}, { ...props, className }, "span")
}

/* The line to the next step. Its `::after` is the fill: give it a colour and it draws itself from
   the start (left, or the top in a vertical stepper) once the next step is reached. */
function StepperConnector({ value, className, ...props }: { value?: string } & PartProps<"span", StateOf<typeof stepper, "connector">>) {
  return usePart(
    stepper,
    "connector",
    (value === undefined ? {} : { value }) as { value: string },
    {
      ...props,
      className: withClass(
        cn(
          "relative overflow-hidden after:absolute after:inset-0 after:content-['']",
          "after:origin-left rtl:after:origin-right after:scale-x-0 data-[orientation=vertical]:after:origin-top data-[orientation=vertical]:after:scale-x-100 data-[orientation=vertical]:after:scale-y-0",
          "after:transition-[scale] after:duration-[calc(300ms*var(--kf-speed,1))] after:ease-house",
          "data-filled:after:scale-x-100 data-[orientation=vertical]:data-filled:after:scale-y-100 data-filled:after:duration-[calc(560ms*var(--kf-speed,1))]",
          "motion-reduce:after:transition-none!",
        ),
        className,
      ),
    },
    "span",
  )
}

/* A step's content, shown while it is current. It arrives from the side someone moved toward. */
function StepperPanel({ value, className, ...props }: { value: string } & PartProps<"div", StateOf<typeof stepper, "panel">>) {
  return usePart(
    stepper,
    "panel",
    { value },
    {
      ...props,
      className: withClass(
        cn(
          "transition-[opacity,translate,filter] duration-[calc(460ms*var(--kf-speed,1))] ease-spring",
          "starting:opacity-0 starting:blur-[6px]",
          "data-[direction=forward]:starting:translate-x-8 data-[direction=backward]:starting:-translate-x-8",
          "data-[orientation=vertical]:data-[direction=forward]:starting:translate-x-0 data-[orientation=vertical]:data-[direction=forward]:starting:translate-y-6",
          "data-[orientation=vertical]:data-[direction=backward]:starting:translate-x-0 data-[orientation=vertical]:data-[direction=backward]:starting:-translate-y-6",
          "motion-reduce:transition-none!",
        ),
        className,
      ),
    },
    "div",
  )
}

export {
  Stepper,
  StepperConnector,
  StepperDescription,
  StepperIndicator,
  StepperItem,
  StepperList,
  StepperPanel,
  StepperStep,
  StepperTitle,
}
export type { StepperOptions, StepperStepData }
```

**components/keyframery/core/stepper-core.ts**

```ts
/* A stepper, as a UI SDK primitive. UI SDK ships none, so it is defined with its core: the same
   definition renders in React, Vue, Svelte, Solid and web components.

   It owns the steps (as data, so every step's place and state is known before anything mounts), the
   current one, how far someone has got, and which way they last moved. Each step is complete,
   current, upcoming or error. Two uses:

   - A read-only progress strip (`interactive: false`): an order that is Placed, Paid, Packed. The
     steps are plain text; the current one carries `aria-current="step"`.
   - An interactive multi-step form: the steps are buttons with one tab stop and arrow keys between
     them (`createRovingFocus`). `linear` (the default) lets people go back to any step they have
     reached but forward only through `next`; without it, any step can be chosen. A step that can't be
     chosen yet is `aria-disabled`, and stays focusable so the arrows don't skip it.

   Follows the pattern UI SDK's patterns page gives for a stepper: a list of buttons with one tab
   stop, the current step marked `aria-current="step"`, no tab or radio roles. */

import { type ChangeDetails, createChange, createRovingFocus, definePrimitive } from "@ui-sdk/core"

type StepperStepState = "complete" | "current" | "upcoming" | "error"

/** One step. */
type StepperStep = {
  /** Unique, and what `value` holds while this step is current. */
  value: string
  /** The step's name: "Shipping". */
  label: string
  /** A line under the name. */
  description?: string
  /** Something on this step needs fixing. Shown as the error state wherever the step is. */
  error?: boolean
  /** Can't be chosen. */
  disabled?: boolean
}

/* "previous-press", "next-press" and "imperative" aren't in the shared vocabulary. */
type StepperValueChangeReason = "item-press" | "previous-press" | "next-press" | "imperative"

type StepperOptions = {
  /** The steps, in order. */
  steps?: readonly StepperStep[]
  /** The current step's value, controlled. */
  value?: string
  /** The current step at first, when uncontrolled. Defaults to the first step. */
  defaultValue?: string
  /** Runs when the current step wants to change. `details.cancel()` stays put, like a step that doesn't validate. */
  onValueChange?: (value: string, details: ChangeDetails<StepperValueChangeReason>) => void
  /** The steps that are done. Defaults to every step before the furthest one reached. Pass every value for a finished flow. */
  completed?: string[]
  /** Steps are buttons people can choose (the default). Off, the stepper is a read-only progress strip. */
  interactive?: boolean
  /** Forward only through `next`; back to any step already reached (the default). Off, any step can be chosen. */
  linear?: boolean
  /** "horizontal" (the default) or "vertical". */
  orientation?: "horizontal" | "vertical"
}

type StepperSummary = { value: string; label: string; state: StepperStepState }

type StepperState = {
  steps: readonly StepperStep[]
  value: string
  /** The furthest step reached, by index. */
  reached: number
  completed: string[] | undefined
  interactive: boolean
  linear: boolean
  orientation: "horizontal" | "vertical"
  /** Which way the last move went, for panels that arrive from that side. */
  direction: "forward" | "backward"
  /** The step with the tab stop. */
  focused: string | null
  /** Every step with its state, for agents and for anyone reading the state. */
  progress: StepperSummary[]
}

const indexOf = (state: Pick<StepperState, "steps">, value: string | null | undefined) =>
  state.steps.findIndex((step) => step.value === value)

/** A step's state: error wins, then current, then complete, else upcoming. */
function stepState(state: StepperState, value: string): StepperStepState {
  const index = indexOf(state, value)
  const step = state.steps[index]
  if (!step) return "upcoming"
  if (step.error) return "error"
  if (value === state.value) return "current"
  if (state.completed) return state.completed.includes(value) ? "complete" : "upcoming"
  return index < state.reached ? "complete" : "upcoming"
}

/** Whether someone can go to this step now. */
function reachable(state: StepperState, value: string) {
  const index = indexOf(state, value)
  const step = state.steps[index]
  if (!state.interactive || !step || step.disabled) return false
  if (!state.linear) return true
  return index <= state.reached || (state.completed?.includes(value) ?? false)
}

const progressOf = (state: StepperState): StepperSummary[] =>
  state.steps.map((step) => ({ value: step.value, label: step.label, state: stepState(state, step.value) }))

const stepper = definePrimitive({
  name: "stepper",
  options: {
    steps: "value",
    value: "string",
    defaultValue: "string",
    onValueChange: "callback",
    completed: "list",
    interactive: "boolean",
    linear: "boolean",
    orientation: "string",
  },
  state: (options: StepperOptions): StepperState => {
    const steps = options.steps ?? []
    const value = options.value ?? options.defaultValue ?? steps[0]?.value ?? ""
    const base: StepperState = {
      steps,
      value,
      reached: Math.max(0, steps.findIndex((step) => step.value === value)),
      completed: options.completed,
      interactive: options.interactive ?? true,
      linear: options.linear ?? true,
      orientation: options.orientation ?? "horizontal",
      direction: "forward",
      focused: null,
      progress: [],
    }
    return { ...base, progress: progressOf(base) }
  },
  sync: (options) => ({
    steps: options.steps ?? [],
    completed: options.completed,
    interactive: options.interactive ?? true,
    linear: options.linear ?? true,
    orientation: options.orientation ?? "horizontal",
    ...(options.value === undefined ? {} : { value: options.value }),
  }),
  controlled: ["value", "progress"],
  api: (context) => {
    const { store } = context
    const change = createChange(context)

    /* However the value or the steps change (a click, a controlled parent, new data), keep how far
       someone got, which way they went and every step's state current. */
    let from = { value: store.get().value, steps: store.get().steps, completed: store.get().completed }
    context.onDestroy(
      store.subscribe(() => {
        const state = store.get()
        if (state.value === from.value && state.steps === from.steps && state.completed === from.completed) return
        const before = indexOf({ steps: from.steps }, from.value)
        const now = indexOf(state, state.value)
        from = { value: state.value, steps: state.steps, completed: state.completed }
        const next = { ...state, reached: Math.max(state.reached, now), direction: now < before ? ("backward" as const) : ("forward" as const) }
        store.set({ reached: next.reached, direction: next.direction, progress: progressOf(next) })
      }),
    )

    const roving = createRovingFocus(context, {
      slot: "step",
      key: "focused",
      orientation: () => store.get().orientation,
      preferred: (step) => step.key === store.get().value,
      claims: (state, step) => step.key === state.value,
    })

    const go = (value: string, reason: StepperValueChangeReason, event?: Event) => {
      const state = store.get()
      if (value === state.value || indexOf(state, value) < 0) return false
      return change("value", value, { reason, event })
    }

    return {
      roving,
      /** Goes to a step, by value or label, if it can be reached now. */
      goTo(step: string, event?: Event) {
        const state = store.get()
        const lower = step.trim().toLowerCase()
        const value = state.steps.find((entry) => entry.value === step || entry.label.toLowerCase() === lower)?.value ?? step
        if (!reachable(state, value)) return false
        return go(value, "item-press", event)
      },
      /** Goes on to the next step (in a linear stepper, the only way forward). */
      next(event?: Event) {
        const state = store.get()
        if (!state.interactive) return false
        const following = state.steps.slice(indexOf(state, state.value) + 1).find((step) => !step.disabled)
        return following ? go(following.value, "next-press", event) : false
      },
      /** Goes back to the step before. */
      previous(event?: Event) {
        const state = store.get()
        if (!state.interactive) return false
        const before = state.steps.slice(0, Math.max(0, indexOf(state, state.value))).reverse().find((step) => !step.disabled)
        return before ? go(before.value, "previous-press", event) : false
      },
      /** The steps, for agents to choose from. */
      items() {
        return store.get().steps.map((step) => ({ value: step.value, label: step.label }))
      },
      /** @internal */
      stateOf: (state: StepperState, value: string) => stepState(state, value),
      /** @internal */
      reachable: (state: StepperState, value: string) => reachable(state, value),
    }
  },
  slots: (slot) => ({
    root: slot<{}, { value: string; orientation: "horizontal" | "vertical"; direction: "forward" | "backward"; interactive: boolean }>({
      role: "group",
      state: (state) => ({ value: state.value, orientation: state.orientation, direction: state.direction, interactive: state.interactive }),
      attrs: (state) => ({
        "data-orientation": state.orientation,
        "data-direction": state.direction,
        "data-interactive": state.interactive ? "" : undefined,
      }),
    }),
    list: slot<{}, { orientation: "horizontal" | "vertical"; steps: readonly StepperStep[] }>({
      state: (state) => ({ orientation: state.orientation, steps: state.steps }),
      attrs: (state) => ({ "data-orientation": state.orientation }),
    }),
    /* One step's place in the list: indicator, text and the connector to the next step. */
    item: slot<{ value: string }, { state: StepperStepState; index: number; last: boolean; orientation: "horizontal" | "vertical" }>({
      props: { value: "string" },
      state: (state, part) => ({
        state: part.api.stateOf(state, part.key),
        index: indexOf(state, part.key),
        last: indexOf(state, part.key) === state.steps.length - 1,
        orientation: state.orientation,
      }),
      attrs: (state, part) => ({
        "data-state": part.api.stateOf(state, part.key),
        "data-orientation": state.orientation,
        "data-last": indexOf(state, part.key) === state.steps.length - 1 ? "" : undefined,
        "aria-current": !state.interactive && state.value === part.key ? "step" : undefined,
      }),
    }),
    /* The step itself: a button in an interactive stepper, plain text in a progress strip. */
    step: slot<{ value: string }, { state: StepperStepState; index: number; reachable: boolean; interactive: boolean }>({
      props: { value: "string" },
      role: (state) => (state.interactive ? "button" : "none"),
      roles: ["button", "none"],
      focus: (state) => (state.interactive ? "roving" : { none: "A read-only progress strip takes no focus." }),
      keys: (state) => (state.orientation === "vertical" ? ["ArrowUp", "ArrowDown", "Home", "End"] : ["ArrowLeft", "ArrowRight", "Home", "End"]),
      state: (state, part) => ({
        state: part.api.stateOf(state, part.key),
        index: indexOf(state, part.key),
        reachable: part.api.reachable(state, part.key),
        interactive: state.interactive,
      }),
      attrs: (state, part) => ({
        type: state.interactive ? "button" : undefined,
        tabindex: state.interactive ? part.api.roving.tabIndex(state, part) : undefined,
        "aria-current": state.interactive && state.value === part.key ? "step" : undefined,
        "aria-disabled": state.interactive && !part.api.reachable(state, part.key) ? "true" : undefined,
        "data-state": part.api.stateOf(state, part.key),
        "data-reachable": part.api.reachable(state, part.key) ? "" : undefined,
      }),
      press: ({ api, key }, event) => void api.goTo(key, event),
      on: {
        keydown: (event, { el, api, store }) => {
          if (el && store.get().interactive) api.roving.keydown(event as KeyboardEvent, el)
        },
      },
      bind: (el, part) => part.api.roving.bind(el, part),
    }),
    indicator: slot<{ value: string }, { state: StepperStepState; index: number }>({
      props: { value: { kind: "string", from: "item" } },
      state: (state, part) => ({ state: part.api.stateOf(state, part.key), index: indexOf(state, part.key) }),
      attrs: (state, part) => ({ "aria-hidden": "true", "data-state": part.api.stateOf(state, part.key) }),
    }),
    title: slot({}),
    description: slot({}),
    /* The line to the next step. `data-filled` once the next step is reached, so it can draw itself. */
    connector: slot<{ value: string }, { filled: boolean }>({
      props: { value: { kind: "string", from: "item" } },
      present: (state, part) => indexOf(state, part.key) < state.steps.length - 1,
      state: (state, part) => {
        const next = state.steps[indexOf(state, part.key) + 1]
        return { filled: !!next && ["complete", "current"].includes(part.api.stateOf(state, next.value)) }
      },
      attrs: (state, part) => {
        const next = state.steps[indexOf(state, part.key) + 1]
        const filled = !!next && ["complete", "current"].includes(part.api.stateOf(state, next.value))
        return { "aria-hidden": "true", "data-filled": filled ? "" : undefined, "data-orientation": state.orientation }
      },
    }),
    /* A step's content, shown while it is current. `data-direction` says which way the move went. */
    panel: slot<{ value: string }, { direction: "forward" | "backward" }>({
      props: { value: "string" },
      present: (state, part) => state.value === part.key,
      state: (state) => ({ direction: state.direction }),
      attrs: (state) => ({ "data-direction": state.direction, "data-orientation": state.orientation }),
    }),
  }),
  agent: { actions: ["goTo", "next", "previous"], closed: true, items: (api) => api.items() },
})

export { stepper, type StepperOptions, type StepperStep, type StepperStepState, type StepperSummary }
```

**Check the import paths**

The files import from `@/components/keyframery/…` and `@/lib/…`. Change those if your project's aliases differ.

## Usage [#usage]

```tsx
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 [#examples]

### A read-only progress strip [#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.

<ExamplePreview name="stepper/progress">
  ```tsx
  import { Stepper, StepperList } from "@/components/keyframery/stepper"

  const steps = [
    { value: "placed", label: "Placed", description: "18 Nov" },
    { value: "paid", label: "Paid", description: "18 Nov" },
    { value: "packed", label: "Packed", description: "19 Nov" },
    { value: "shipped", label: "Shipped" },
    { value: "delivered", label: "Delivered" },
  ]

  export default function StepperProgress() {
    return (
      <Stepper aria-label="Order progress" interactive={false} steps={steps} value="paid" className="max-w-xl">
        <StepperList />
      </Stepper>
    )
  }
  ```
</ExamplePreview>

### A multi-step form [#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.

<ExamplePreview name="stepper/form">
  ```tsx
  import * as React from "react"

  import { Button } from "@/components/keyframery/button"
  import { Stepper, StepperList, StepperPanel } from "@/components/keyframery/stepper"

  const steps = [
    { value: "account", label: "Account" },
    { value: "team", label: "Team" },
    { value: "billing", label: "Billing" },
  ]

  export default function StepperForm() {
    const [step, setStep] = React.useState("account")
    const index = steps.findIndex((s) => s.value === step)
    return (
      <Stepper aria-label="Set up workspace" steps={steps} value={step} onValueChange={setStep} className="max-w-lg">
        <StepperList />
        <div className="grid text-[13px] *:[grid-area:1/1]">
          <StepperPanel value="account">Choose a name and a password.</StepperPanel>
          <StepperPanel value="team">Invite the people you work with.</StepperPanel>
          <StepperPanel value="billing">Add a card. You won't be charged during the trial.</StepperPanel>
        </div>
        <div className="flex justify-between">
          <Button variant="ghost" disabled={index === 0} onClick={() => setStep(steps[index - 1].value)}>Back</Button>
          <Button variant="primary" disabled={index === steps.length - 1} onClick={() => setStep(steps[index + 1].value)}>Continue</Button>
        </div>
      </Stepper>
    )
  }
  ```
</ExamplePreview>

### Vertical, non-linear, with an error [#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.

<ExamplePreview name="stepper/vertical">
  ```tsx
  import { Stepper, StepperList } from "@/components/keyframery/stepper"

  const steps = [
    { value: "details", label: "Details", description: "Name and logo" },
    { value: "domain", label: "Domain", description: "DNS records not found", error: true },
    { value: "email", label: "Email", description: "Sender address" },
    { value: "launch", label: "Launch" },
  ]

  export default function StepperVertical() {
    return (
      <Stepper aria-label="Store setup" orientation="vertical" linear={false} steps={steps} defaultValue="email" className="max-w-xs">
        <StepperList />
      </Stepper>
    )
  }
  ```
</ExamplePreview>

## Motion [#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](/docs/motion-styles) you set. To change how fast this stepper moves, pass `speed`:

```tsx
<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 [#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 [#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 [#stepper]

Renders a `<div>`, and takes its props too.

<PropsTable rows="[{&#x22;name&#x22;:&#x22;speed&#x22;,&#x22;type&#x22;:&#x22;\&#x22;fast\&#x22; | \&#x22;normal\&#x22; | \&#x22;slow\&#x22; | number&#x22;,&#x22;default&#x22;:null,&#x22;description&#x22;:&#x22;How fast it moves: \&#x22;fast\&#x22;, \&#x22;normal\&#x22;, \&#x22;slow\&#x22; or a multiplier.&#x22;,&#x22;required&#x22;:false},{&#x22;name&#x22;:&#x22;steps&#x22;,&#x22;type&#x22;:&#x22;readonly StepperStep[]&#x22;,&#x22;full&#x22;:&#x22;readonly StepperStep[]&#x22;,&#x22;default&#x22;:null,&#x22;description&#x22;:&#x22;The steps, in order: `{ value, label, description?, error?, disabled? }`.&#x22;,&#x22;required&#x22;:false},{&#x22;name&#x22;:&#x22;value&#x22;,&#x22;type&#x22;:&#x22;string&#x22;,&#x22;full&#x22;:&#x22;string&#x22;,&#x22;default&#x22;:null,&#x22;description&#x22;:&#x22;The current step's value, controlled.&#x22;,&#x22;required&#x22;:false},{&#x22;name&#x22;:&#x22;defaultValue&#x22;,&#x22;type&#x22;:&#x22;string&#x22;,&#x22;full&#x22;:&#x22;string&#x22;,&#x22;default&#x22;:null,&#x22;description&#x22;:&#x22;The current step at first, when uncontrolled. Defaults to the first.&#x22;,&#x22;required&#x22;:false},{&#x22;name&#x22;:&#x22;onValueChange&#x22;,&#x22;type&#x22;:&#x22;function&#x22;,&#x22;full&#x22;:&#x22;(value: string, details: ChangeDetails<\&#x22;imperative\&#x22; | \&#x22;item-press\&#x22; | \&#x22;previous-press\&#x22; | \&#x22;next-press\&#x22;>) => void&#x22;,&#x22;default&#x22;:null,&#x22;description&#x22;:&#x22;Runs with the next step. `details.reason` is \&#x22;item-press\&#x22;, \&#x22;next-press\&#x22;, \&#x22;previous-press\&#x22; or \&#x22;imperative\&#x22;; `details.cancel()` stays, like a step that doesn't validate.&#x22;,&#x22;required&#x22;:false},{&#x22;name&#x22;:&#x22;completed&#x22;,&#x22;type&#x22;:&#x22;string[]&#x22;,&#x22;full&#x22;:&#x22;string[]&#x22;,&#x22;default&#x22;:null,&#x22;description&#x22;:&#x22;The steps that are done. Defaults to every step before the furthest one reached. Pass every value for a finished flow.&#x22;,&#x22;required&#x22;:false},{&#x22;name&#x22;:&#x22;interactive&#x22;,&#x22;type&#x22;:&#x22;boolean&#x22;,&#x22;full&#x22;:&#x22;boolean&#x22;,&#x22;default&#x22;:null,&#x22;description&#x22;:&#x22;Steps are buttons (the default). Off, it is a read-only progress strip with `aria-current=\&#x22;step\&#x22;` on the current one.&#x22;,&#x22;required&#x22;:false},{&#x22;name&#x22;:&#x22;linear&#x22;,&#x22;type&#x22;:&#x22;boolean&#x22;,&#x22;full&#x22;:&#x22;boolean&#x22;,&#x22;default&#x22;:null,&#x22;description&#x22;:&#x22;Forward only through `next`, back to any step reached (the default). Off, any step can be chosen.&#x22;,&#x22;required&#x22;:false},{&#x22;name&#x22;:&#x22;orientation&#x22;,&#x22;type&#x22;:&#x22;\&#x22;horizontal\&#x22; | \&#x22;vertical\&#x22;&#x22;,&#x22;full&#x22;:&#x22;\&#x22;horizontal\&#x22; | \&#x22;vertical\&#x22;&#x22;,&#x22;default&#x22;:null,&#x22;description&#x22;:&#x22;\&#x22;horizontal\&#x22; (the default) or \&#x22;vertical\&#x22;.&#x22;,&#x22;required&#x22;:false}]" />

### StepperPanel [#stepperpanel]

Renders a `<div>`, and takes its props too.

<PropsTable rows="[{&#x22;name&#x22;:&#x22;value&#x22;,&#x22;type&#x22;:&#x22;string&#x22;,&#x22;full&#x22;:&#x22;string&#x22;,&#x22;default&#x22;:null,&#x22;description&#x22;:&#x22;The step whose content this is. Shown while that step is current.&#x22;,&#x22;required&#x22;:true}]" />

### Other parts [#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 [#keyboard]

| Key                               | What it does                                               |
| --------------------------------- | ---------------------------------------------------------- |
| <kbd>Tab</kbd>                    | Moves into the steps as one tab stop, on the current step. |
| <kbd>ArrowRight / ArrowLeft</kbd> | Moves between steps (ArrowDown and ArrowUp when vertical). |
| <kbd>Home / End</kbd>             | Moves to the first or last step.                           |
| <kbd>Enter / Space</kbd>          | Goes to the focused step, if it can be reached.            |

## Accessibility [#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](/docs/accessibility).

## Built on UI SDK's core [#built-on-ui-sdks-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.
