docs
Introduction
BetaArchitecture notes for composing Stepper into real product flows without coupling the primitive to forms, routes, or validation.
Flow architecture
Stepper is the progress layer. Your app keeps the business rules, validation, routing, persistence, and async work.
- App state
- source of truth
- Routes, forms, server data, and persistence decide what the flow means.
- Stepper
- progress layer
- Registers steps, normalizes navigation, exposes ARIA, and reflects state.
- Adapters
- integration edge
- React Hook Form, Zod, Zustand, and animation layers connect around the primitive.
Composition patterns
Start with the primitive structure, then replace the visual parts that need product-specific behavior.
stepper-composition.txt
Copy code is available in the top right.
Stepper
├── StepperList
│ ├── StepperItem
│ │ ├── StepperTrigger
│ │ │ ├── StepperIndicator
│ │ │ ├── StepperLabel
│ │ │ └── StepperDescription
│ │ └── StepperSeparator
│ └── StepperItem
├── StepperContent
├── StepperPrevious
└── StepperNextIntegration boundary
Adapters sit around the primitive. They feed state into Stepper instead of making Stepper own the entire workflow.
- react-hook-form
- Validation
- Owns field state and step validation in examples.
- zod
- Schema
- Defines form rules without coupling to the primitive.
- Next.js
- Routes
- Use StepperTrigger asChild with Link for route-based flows.
- shadcn/ui Form
- Fields
- Compose Field, Input, Select, Alert, and Button around the primitive.
- Server Actions
- Submit
- Keep persistence outside the Stepper while the UI reflects progress.
- Radix Slot
- asChild
- Used only for custom trigger/content composition.
Next
Install the source, then open the component reference when you need examples, composition, and API details.