How to Add a Stepper to a React App

Before installing Stepper, confirm your React project has the two things Drivn assumes: Tailwind CSS v4 installed and processing your styles, and a @/ path alias pointing at your source directory — the component ships as a .tsx file, so TypeScript is part of the stack. If you scaffolded with create-next-app, npm create vite, or npx drivn@latest create, both are already wired; for a custom setup the installation page lists the minimal config. The Stepper's only third-party import is the Check icon from lucide-react, which renders inside a completed step, so make sure lucide-react is installed. The one detail worth knowing before you render it is that the Stepper is a Client Component: each indicator is a clickable button and the parts read the active step through React context, so its source opens with a 'use client' directive and renders inside a client boundary rather than straight in a Server Component.

Run the CLI from your project root to add the Stepper source file. The command prompts once for your install directory (defaulting to src/components/ui/) and writes a single stepper.tsx — no other files, because the component's only dependency past React is the cn utility and the Check icon. No global config file is created; the result is TypeScript source you edit like any other component. Confirm it landed in your editor, then commit it for a clean baseline. If your project uses a monorepo layout or a non-standard source path, the CLI docs cover the flags for targeting a custom location during install. Because the file is yours after install, future Drivn releases will not overwrite your edits — the whole control, from the index-injection logic to the styling object, is one file you can read top to bottom.

Import Stepper and render it inside a Client Component. The simplest form takes bare <Stepper.Item /> children with no props: the root walks its children with React.Children.toArray, injects each item's position as an internal _index, and an item with no label or icon renders that index plus one — so four items read as 1, 2, 3, 4. Pass the root a step number and the item at that index renders active, everything before it renders completed with a checkmark, and everything after renders upcoming. The example below shows a four-step stepper fixed at step 1. Because the file opens with 'use client', drop this into a client component or a page already inside a client boundary; the Next.js Stepper guide covers importing it into a Server Component page.

The Stepper has no internal step state — it renders exactly the step number you hand it, so the active step always lives in your component. To move through the flow, pair the Stepper with a couple of Button controls that increment and decrement the state, clamped to the number of steps. The onStepChange callback also fires with an item's index when a user clicks that step's indicator, so wiring it to your setter lets people jump directly to a step as well as page through with buttons. The example holds step in useState, advances it with Next and Back buttons, and disables each at the ends of the range. Because the value is yours, a form on the last step can read it, and a completed step's checkmark appears automatically once step passes that index.

Each Stepper.Item takes three optional props. label puts a short text caption inside the indicator; icon accepts a lucide component reference — icon={User}, not a rendered <User /> — which the Stepper sizes for you; and disabled blocks clicks on that step. The indicator shows a checkmark once its step is complete, otherwise the label, then the icon, then the auto-number, in that order of precedence. On the root, orientation="vertical" stacks the items in a column with the connecting line running top to bottom, and line={false} drops the connectors entirely for a compact pager. Everything visible is a Tailwind class in the styles object inside the file you own, so recoloring a state is a one-line edit that every Stepper follows — see Theming for the tokens. The example shows an icon stepper and a vertical labelled stepper. For more copy-paste variants see the Stepper examples.