API

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

import { defineStepper } from "@/components/ui/stepper";

const { Stepper } = defineStepper(
  { id: "step-1", title: "Step 1" },
  { id: "step-2", title: "Step 2" },
  { id: "step-3", title: "Step 3" }
);

export function Component() {
  return (
    <Stepper.Provider>
      <Stepper.Navigation>
        <Stepper.Step>
          <Stepper.Title />
          <Stepper.Description />
        </Stepper.Step>
        ...
      </Stepper.Navigation>
      <Stepper.Panel />
      <Stepper.Controls>...</Stepper.Controls>
    </Stepper.Provider>
  );
}

Your first Stepper

Let's start with the most basic stepper. A stepper with a horizontal navigation.

Create a stepper instance with the defineStepper function.

const { Stepper, ... } = defineStepper(
  { id: "step-1", title: "Step 1" },
  { id: "step-2", title: "Step 2" },
  { id: "step-3", title: "Step 3" }
)

Wrap your application in a Stepper.Provider component.

export function MyFirstStepper() {
  return <Stepper.Provider>...</Stepper.Provider>;
}

Add a Stepper.Navigation component to render the navigation buttons and labels.

const { Stepper } = defineStepper(
  { id: "step-1", title: "Step 1" },
  { id: "step-2", title: "Step 2" },
  { id: "step-3", title: "Step 3" }
);
export function MyFirstStepper() {
  return (
    <Stepper.Provider>
      {({ methods }) => (
        <Stepper.Navigation>
          {methods.all.map((step) => (
            <Stepper.Step of={step.id} onClick={() => methods.goTo(step.id)}>
              <Stepper.Title>{step.title}</Stepper.Title>
            </Stepper.Step>
          ))}
        </Stepper.Navigation>
      )}
    </Stepper.Provider>
  );
}

Add a Stepper.Panel component to render the content of the step.

const { Stepper, ... } = defineStepper(
  { id: "step-1", title: "Step 1" },
  { id: "step-2", title: "Step 2" },
  { id: "step-3", title: "Step 3" }
)

export function MyFirstStepper() {
  return (
    <Stepper.Provider>
      {({ methods }) => (
        <>
          {/* Stepper.Navigation code */}
          {methods.switch({
            "step-1": (step) => <StepperPanel />,
            "step-2": (step) => <StepperPanel />,
            "step-3": (step) => <StepperPanel />,
          })}
        </>
      )}
    </Stepper.Provider>
  )
}

Add a Stepper.Controls component to render the buttons to navigate through the steps.

const { Stepper, ... } = defineStepper(
  { id: "step-1", title: "Step 1" },
  { id: "step-2", title: "Step 2" },
  { id: "step-3", title: "Step 3" }
)

export function MyFirstStepper() {
  return (
    <Stepper.Provider>
      {({ methods }) => (
        <>
          {/* Stepper.Navigation code */}
          {/* Stepper.Panel code */}
          <Stepper.Controls>
            {!methods.isLast && (
              <Button
                variant="secondary"
                onClick={methods.prev}
                disabled={methods.isFirst}
              >
                Previous
              </Button>
            )}
            <Button onClick={methods.isLast ? methods.reset : methods.next}>
              {methods.isLast ? "Reset" : "Next"}
            </Button>
          </Stepper.Controls>
        </>
      )}
    </Stepper.Provider>
  )
}

Add some styles to make it look nice.

const { Stepper } = defineStepper(
  { id: "step-1", title: "Step 1" },
  { id: "step-2", title: "Step 2" },
  { id: "step-3", title: "Step 3" }
);

export function MyFirstStepper() {
  return (
    <Stepper.Provider className="space-y-4">
      {({ methods }) => (
        <>
          <Stepper.Navigation>
            {methods.all.map((step) => (
              <Stepper.Step of={step.id} onClick={() => methods.goTo(step.id)}>
                <Stepper.Title>{step.title}</Stepper.Title>
              </Stepper.Step>
            ))}
          </Stepper.Navigation>
          {methods.switch({
            "step-1": (step) => <Content id={step.id} />,
            "step-2": (step) => <Content id={step.id} />,
            "step-3": (step) => <Content id={step.id} />,
          })}
          <Stepper.Controls>
            {!methods.isLast && (
              <Button
                type="button"
                variant="secondary"
                onClick={methods.prev}
                disabled={methods.isFirst}
              >
                Previous
              </Button>
            )}
            <Button onClick={methods.isLast ? methods.reset : methods.next}>
              {methods.isLast ? "Reset" : "Next"}
            </Button>
          </Stepper.Controls>
        </>
      )}
    </Stepper.Provider>
  );
}

const Content = ({ id }: { id: string }) => {
  return (
    <Stepper.Panel className="h-[200px] content-center rounded border bg-slate-50 p-8">
      <p className="text-xl font-normal">Content for {id}</p>
    </Stepper.Panel>
  );
};

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:

const stepperInstance = defineStepper(
  { id: "step-1", title: "Step 1", description: "Step 1 description" },
  { id: "step-2", title: "Step 2", description: "Step 2 description" },
  { id: "step-3", title: "Step 3", description: "Step 3 description" }
);

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:

const { Stepper, useStepper } = defineStepper(
  { id: "step-1", title: "Step 1" },
  { id: "step-2", title: "Step 2" },
  { id: "step-3", title: "Step 3" }
);

export function MyStepper() {
  const methods = useStepper(); // ❌ This won't work if the component is not within the provider
  return (
    <Stepper.Provider>
      <MyCustomComponent />
    </Stepper.Provider>
  );
}

function MyCustomComponent() {
  const methods = useStepper(); // ✅ This will work
  return <div>{methods.currentStep.title}</div>;
}

You also get access to the methods in the children's component

export function MyStepper() {
  return (
    <Stepper.Provider>
      {({ methods }) => (
        ...
      )}
    </Stepper.Provider>
  )
}

You can set the initial step and metadata for the stepper passing these props:

initialStep - The ID of the initial step to display
initialMetadata - 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:

methods.beforeNext(async () => {
  const valid = await form.trigger();
  if (!valid) return false;
  return true;
});

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.

// From step 1 to step 3
methods.goTo("step-3");

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.

const { metadata, getMetadata, setMetadata, resetMetadata } = useStepper();

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.

const stepperInstance1 = defineStepper(
  { id: "step-1", title: "Step 1" },
  { id: "step-2", title: "Step 2" },
  { id: "step-3", title: "Step 3" }
)

const stepperInstance2 = defineStepper(
  { id: "step-1", title: "Step 1" },
  { id: "step-2", title: "Step 2" },
  { id: "step-3", title: "Step 3" }
)

<stepperInstance1.Stepper.Provider>
  <stepperInstance2.Stepper.Provider>
    ...
  </stepperInstance2.Stepper.Provider>
</stepperInstance1.Stepper.Provider>

Structure

Usage

Your first Stepper

Components

defineStepper

useStepper

Stepper.Provider

Stepper.Navigation

Stepper.Step

Stepper.Title

Stepper.Description

Stepper.Panel

Stepper.Controls

Before/after actions

Skip steps

Metadata

Multi Scoped

On this page