API
API reference for shadcn-stepper
Structure
A Stepper
component is composed of the following parts:
Provider
- Handles the stepper logic.Navigation
- Contains the buttons and labels to navigate through the steps.Step
- Step component.Title
- Step title.Description
- Step description.Panel
- Section to render the step content based on the current step.Controls
- Section to render the buttons to navigate through the steps.
Usage
Your first Stepper
Let's start with the most basic stepper. A stepper with a horizontal navigation.
defineStepper
function.Stepper.Provider
component.Add a Stepper.Navigation
component to render the navigation buttons and
labels.
Stepper.Panel
component to render the content of the step.Add a Stepper.Controls
component to render the buttons to navigate through
the steps.
Components
The components in stepper.tsx
are built to be composable i.e you build your stepper by putting the provided components together.
They also compose well with other shadcn/ui components such as DropdownMenu, Collapsible or Dialog etc.
If you need to change the code in stepper.tsx
, you are encouraged to do so. The code is yours. Use stepper.tsx
as a starting point and build your own.
In the next sections, we'll go over each component and how to use them.
If you want to use @stepperize/react API directly, like when
,
switch
, match
, etc. you can use the useStepper
hook from your stepper
instance and build your own components.
defineStepper
The defineStepper
function is used to define the steps. It returns a Stepper
instance with a hook and utils to interact with the stepper.
Unlike @stepperize/react
, defineStepper
also offers all the components for rendering the stepper.
For example, you can define the steps like this:
Each instance will return:
steps
- Array of steps.useStepper
- Hook to interact with the stepper component.utils
- Provides a set of pure functions for working with steps.
And the Stepper
abstract component with the following compound components:
Stepper.Provider
Stepper.Navigation
Stepper.Step
Stepper.Title
Stepper.Description
Stepper.Panel
Stepper.Controls
Each step in the defineStepper
needs only an id
to work and they are not
limited to any type. You can define anything within each step, even
components!
useStepper
The useStepper
hook is used to interact with the stepper. It provides methods to interact with and render your stepper.
Stepper.Provider
The Stepper.Provider
component is used to provide the stepper instance from defineStepper
to the other components. You should always wrap your application in a StepperProvider
component.
Allow us to work with the useStepper
hook in components that are within the provider.
For example:
You also get access to the methods in the children's component
You can set the initial step and metadata for the stepper passing these props:
initialStep
- The ID of the initial step to displayinitialMetadata
- The initial metadata to set for the steps. See Metadata for more information.
If you don't need the methods
prop, you can just pass the children directly
and get the methods from the useStepper
hook from your stepper instance.
Props
Name | Type | Description |
---|---|---|
variant | horizontal, vertical or circle | Style of the stepper. |
labelOrientation | horizontal, vertical | Orientation of the labels. This is only applicable if variant is "horizontal" . |
tracking | boolean | Track the scroll position of the stepper. |
initialStep | string | Initial step to render. |
initialMetadata | Record<string, any> | Initial metadata. |
Stepper.Navigation
The Stepper.Navigation
component is used to render the navigation buttons and labels.
Stepper.Step
The Stepper.Step
component is a wrapper of the button and labels. You just need to pass the of
prop which is the step id you want to render.
This is a good place to add your onClick
handler.
Props
Name | Type | Description |
---|---|---|
of | string | Step to render. |
icon | React.ReactNode | Icon to render instead of the step number |
To keep the stepper simple and consistent, StepperStep
only accepts these 3
types of children: StepperTitle
, StepperDescription
and StepperPanel
Stepper.Title
The Stepper.Title
component is used to render the title of the step.
Props
Name | Type | Description |
---|---|---|
children | React.ReactNode | Title to render. |
asChild | boolean | Render as child. |
Stepper.Description
The Stepper.Description
component is used to render the description of the step.
Props
Name | Type | Description |
---|---|---|
children | React.ReactNode | Description to render. |
asChild | boolean | Render as child. |
Stepper.Panel
The Stepper.Panel
component is used to render the content of the step.
Props
Name | Type | Description |
---|---|---|
children | React.ReactNode | Content to render. |
asChild | boolean | Render as child. |
Stepper.Controls
The Stepper.Controls
component is used to render the buttons to navigate through the steps.
Props
Name | Type | Description |
---|---|---|
children | React.ReactNode | Buttons to render. |
asChild | boolean | Render as child. |
Before/after actions
You can add a callback to the next
and prev
methods to execute a callback before or after the action is executed.
This is useful if you need to validate the form or check if the step is valid before moving to the prev/next step.
For example:
That function will validate the form and check if the step is valid before moving to the next step returning a boolean value.
More info about the beforeNext
and beforePrev
methods can be found in the API References.
Skip steps
Through the methods you can access functions like goTo
to skip to a specific step.
Metadata
You can add metadata to each step to store any information you need. This data can be accessed in the useStepper
hook and changed at any time.
If you need more information about the metadata, you can read the Metadata section in the API References.
Multi Scoped
The Stepper.Provider
component can be used multiple times in the same application. Each instance will be independent from the others.
Last updated on