Drivn vs shadcn/ui — Stepper Compared

Run npx shadcn@latest add stepper and the CLI fails with "component not found". Open the shadcn/ui component index and the list jumps from Slider to Switch — no Stepper between them. The shadcn philosophy treats the Stepper as a composition problem: take the Progress bar primitive, render a row of styled Button elements above it, manage the active index in useState, and you have a stepper. That works, and many shadcn projects do exactly this, but it is a build job rather than an install job.

Drivn treats the Stepper as a primitive in its own right. The component is in the registry alongside Accordion, Dialog, and Tabs, and the Drivn CLI writes it into @/components/ui/stepper.tsx like any other piece. The file is yours after install — read it, edit it, restyle it — but the starting point is a working component, not a recipe.

The Drivn Stepper uses the dot-notation pattern that the rest of the library follows: <Stepper> is the parent that holds the step index and the optional onStepChange callback, and <Stepper.Item /> is the child that renders one indicator. Items take no props in the simplest case — the parent walks React.Children.toArray(children) and injects an internal _index prop via React.cloneElement, so the first child becomes step 0, the second step 1, and so on. The indicator content defaults to the index plus one — 1, 2, 3, 4.

Pass a label and the indicator widens with px-3 and renders the label text instead of the number. Pass an icon and the indicator renders that icon instead. Once a step is below the current step value, the indicator switches to the completed state and renders a Check icon regardless of label or icon. Read the full props table on the Stepper docs page.

Every Stepper.Item computes its state from its _index against the parent's step: indices below step are completed, the matching index is active, every index above is upcoming. The styles.indicator object holds the visual rules for each state — completed uses bg-primary text-muted-foreground and renders the Check icon, active uses bg-accent with a border-2 border-primary ring, upcoming uses bg-accent with a faded border-border ring. The transitions are pure CSS transition-colors duration-200 so stepping forward animates without any framer-motion dependency.

Between every pair of adjacent items the Stepper renders a connector line — h-0.5 flex-1 in horizontal mode, w-0.5 min-h-6 self-center in vertical mode — coloured bg-primary when its index is below step and bg-border otherwise. Pass line={false} to drop the connectors entirely, useful for compact pagers and onboarding pills.

Two situations push you toward composing a stepper on top of shadcn primitives rather than reaching for the Drivn version. The first is a project already deep in shadcn with a strict "no other registries" rule — adding Drivn means another CLI in the build, another set of conventions, and another @/components/ui source you maintain. If your design system mandates shadcn-only, the right call is to compose a Stepper from the existing Progress primitive and a row of Button elements.

The second is a stepper with strongly custom behaviour — branching flows where step 3 conditionally jumps to step 5, animated indicator transitions with framer-motion, per-step validation that blocks forward navigation, or asynchronous step completion that swaps the indicator for a spinner. The Drivn Stepper exposes onStepChange for click-to-jump and disabled per item, but the more exotic behaviour lives in your wrapper component on top. At that point the Drivn file is still useful — copy it and extend — but a from-scratch composition can be more direct.