Stepper – React component

Your details (completed)
Name and work email
2
Company details
Company name and team size
3
Invite your team
Add colleagues by email
4
Connect integrations
Link the tools your team already uses

"use client";

import { Stepper, StepperItem } from "@/siteplane/components/stepper";

export default function Example() {
  return (
    <Stepper aria-label="Onboarding progress" className="w-full max-w-xs">
      <StepperItem
        status="done"
        title="Your details"
        description="Name and work email"
      />
      <StepperItem
        status="current"
        index={2}
        title="Company details"
        description="Company name and team size"
      />
      <StepperItem
        index={3}
        title="Invite your team"
        description="Add colleagues by email"
      />
      <StepperItem
        index={4}
        title="Connect integrations"
        description="Link the tools your team already uses"
      />
    </Stepper>
  );
}

Installation

pnpm dlx shadcn@4.18.0 add @siteplane/stepper

Complete the one-time setup first. Registry JSON lists source files and dependencies.

For this page’s examples, also install:

pnpm dlx shadcn@4.18.0 add @siteplane/button @siteplane/input

Usage

import { Stepper, StepperItem } from "@/siteplane/components/stepper";

<Stepper>
  <StepperItem index={1} title="Profile" />
</Stepper>;

Composition

Stepper
├── StepperItem
└── StepperButtonItem

Use StepperButtonItem when people can go back to steps they have already reached. Two props describe a step and they are independent: status says where the step stands (done, current, open or blocked) and active says which step is open. Opening another step changes active only, so a completed step keeps its check and the step in progress keeps its marker wherever the person is. Your application decides each status and which steps are available: disable steps that haven’t been reached yet, and set disabled with status="blocked", which changes only the marker.

"use client";

import { useState } from "react";
import { Stepper, StepperButtonItem } from "@/siteplane/components/stepper";

// `status` says where each step stands. It never depends on which step is selected.
const steps = [
  { title: "Account", description: "Name and sign-in email", status: "done" },
  {
    title: "Workspace",
    description: "Workspace name and address",
    status: "current",
  },
  { title: "Billing", description: "Plan and payment method", status: "open" },
] as const;

const furthestReachedStep = 1;

export default function Example() {
  const [selected, setSelected] = useState(furthestReachedStep);
  return (
    <Stepper aria-label="Workspace setup" className="w-full max-w-xs">
      {steps.map((step, index) => (
        <StepperButtonItem
          key={step.title}
          active={index === selected}
          description={step.description}
          disabled={index > furthestReachedStep}
          index={index + 1}
          onClick={() => setSelected(index)}
          status={step.status}
          title={step.title}
        />
      ))}
      <StepperButtonItem
        description="Available after billing is set up"
        disabled
        status="blocked"
        title="Review and launch"
      />
    </Stepper>
  );
}

Steps with content

Pass children to a step to show content under its title, such as the form of the current step. The content opens when the children appear and closes when they go away, with the same expand and fade as every other change in the kit. Keep one item per step, each with a stable key, and pass children only to the step that is open: the markers, their colors, the descriptions and the connector then change in place instead of the steps being replaced.

In a StepperButtonItem the content sits under the button, never inside it, so it can hold fields and links. The title and the status of the button name it; the content is not part of its name.

"use client";

import { useState } from "react";
import { Button } from "@/siteplane/components/button";
import { Input } from "@/siteplane/components/input";
import { Stepper, StepperButtonItem } from "@/siteplane/components/stepper";

const steps = [
  { title: "Workspace", hint: "Name the workspace" },
  { title: "Team", hint: "Invite the people you work with" },
  { title: "Launch", hint: "Review and create the workspace" },
];

export default function Example() {
  const [selected, setSelected] = useState(0);
  const [reached, setReached] = useState(0);
  const [name, setName] = useState("Northlight Studio");
  const [email, setEmail] = useState("");

  const summaries = [
    name.trim() || steps[0]!.hint,
    email.trim() || "Nobody invited yet",
    steps[2]!.hint,
  ];

  return (
    <div className="grid w-full max-w-sm gap-6">
      <Stepper aria-label="Workspace setup">
        {steps.map((step, index) => (
          <StepperButtonItem
            key={step.title}
            active={index === selected}
            description={
              index < reached && index !== selected
                ? summaries[index]
                : step.hint
            }
            disabled={index > reached}
            index={index + 1}
            onClick={() => setSelected(index)}
            status={
              index < reached ? "done" : index === reached ? "current" : "open"
            }
            title={step.title}
          >
            {index === selected ? (
              index === 0 ? (
                <Input
                  aria-label="Workspace name"
                  onChange={(event) => setName(event.target.value)}
                  value={name}
                />
              ) : index === 1 ? (
                <Input
                  aria-label="Teammate email"
                  onChange={(event) => setEmail(event.target.value)}
                  placeholder="teammate@northlight.studio"
                  type="email"
                  value={email}
                />
              ) : (
                <p className="text-muted-foreground text-sm">
                  {name.trim() || "Your workspace"} is ready to be created.
                </p>
              )
            ) : null}
          </StepperButtonItem>
        ))}
      </Stepper>
      <div className="flex justify-between gap-2">
        <Button
          disabled={selected === 0}
          onClick={() => setSelected(selected - 1)}
          variant="outline"
        >
          Back
        </Button>
        <Button
          disabled={selected === steps.length - 1}
          onClick={() => {
            setSelected(selected + 1);
            setReached(Math.max(reached, selected + 1));
          }}
          variant="accent"
        >
          Continue
        </Button>
      </div>
    </div>
  );
}

A step moves between clickable and open without being replaced. Use StepperButtonItem for every step that people can open, and give it active while it is open.

API reference

Component properties
Prop	Type	Default	Description
`Item / ButtonItem.title`	`ReactNode`	`required`	Step title.
`description`	`ReactNode`	`unset`	Supporting text under the title. Text that changes cross-fades; give a description element a key to cross-fade between elements, or keep the same key to update it in place.
`children`	`ReactNode`	`unset`	The content of the step, shown under its title. It expands when children appear and collapses when they go away; in a StepperButtonItem it sits outside the button.
`index`	`number`	`unset`	Marker number for open/current states.
`status`	`open \| current \| done \| blocked`	`open`	Where the step stands: its marker and text. It does not depend on which step is open; see StepperButtonItem.active.
`statusLabel`	`string`	`done: "completed", blocked: "blocked"`	Visually hidden status text after the title, read as "Title (completed)". Replace it to translate, or pass an empty string to omit it.
`StepperButtonItem.active`	`boolean`	`false`	The step that is open: aria-current=step and the selection ring, independently of status. A done step keeps its check while it is open. current is a deprecated alias.
`StepperButtonItem.disabled`	`boolean`	`false`	Prevents activation.
`StepperButtonItem.onClick`	`MouseEventHandler`	`unset`	Navigate/change current step.

Stepper accepts native ol props. StepperItemProps extends li props without native title; status=current sets aria-current=step. StepperButtonItemProps extends button props without native title and adds active; it uses a text Button. Both accept children for the content of the step and string className. The internal indicator/content helpers and status type are not exported. No automatic progression, validation or navigation is provided.

Every change animates through the shared motion tokens: the content expands and collapses, the marker changes its number, check or lock and its colors, a changed description cross-fades, and the connector follows the height of its step. All of it is instant when the system asks for reduced motion, when html carries data-motion-reduce="true", or inside SiteplaneMotionProvider preset="reduced".

Read the installed source.

Usage notes

The marker shows done and blocked steps only as an icon, so each title adds visually hidden status text for screen readers. Interactive steps use normal button keyboard behavior. Use Tabs if the interaction is a set of associated panels rather than a sequence.

The markers sit at the inline start of the steps and the connector runs down under them, so in a right-to-left page both are on the right.

Replacing one item component with another at the same position, for example StepperItem for the open step and StepperButtonItem for the others, remounts the step and loses the transition. Use StepperButtonItem for all of them.

Content that is closing is inert and hidden from assistive technology while it collapses, so focus inside it is lost when it closes. Move focus to the next control when a step closes.