# Stepper
**Category**: react
**URL**: https://ui.darkcode.dev/en/docs/react/components/stepper
**Source**: https://raw.githubusercontent.com/DarkCode-Developers/darkcode-ui/refs/heads/main/apps/docs/content/docs/en/react/components/(navigation)/stepper.mdx
> A step-by-step progress indicator with numbered, icon, and bullet variants in horizontal or vertical layouts.
***
## Import
```tsx
import { Stepper } from '@darkcode-ui/react';
```
### Usage
The `currentStep` (controlled) or `defaultStep` (uncontrolled) prop marks the active step. Every step before it is automatically rendered as complete.
### Anatomy
Import the Stepper component and access all parts using dot notation.
```tsx
import { Stepper } from '@darkcode-ui/react';
export default () => (
{/* Optional, rendered inside the indicator */}
{/* Optional */}
{/* Hidden on the last step */}
)
```
### With Icons
Return a `` from the `` render function for inactive and active steps. Returning `undefined` for completed steps falls back to the default animated checkmark.
### With Descriptions
Add a `` next to the `` inside ``.
### Sizes
Use the `size` prop to render `sm`, `md` (default), or `lg` steppers.
### Bullet Steps
Pass empty children and a smaller size to `` to render minimal bullet markers instead of numbers.
### Vertical
Set `orientation="vertical"` to stack steps with a vertical connector.
### Vertical Sizes
### Vertical With Icons
### Controlled
Provide `currentStep` together with `onStepChange` to control the active step. Passing `onStepChange` also makes each step clickable.
```tsx
"use client";
import {Button, Stepper} from "@darkcode-ui/react";
import React from "react";
const steps = ["Account", "Profile", "Review"];
export function Controlled() {
const [step, setStep] = React.useState(0);
return (
{steps.map((title) => (
{title}
))}
);
}
```
### Controlled Vertical
```tsx
"use client";
import {Button, Stepper} from "@darkcode-ui/react";
import React from "react";
const steps = [
{description: "Enter your account details", title: "Account"},
{description: "Set up your profile", title: "Profile"},
{description: "Confirm and finish", title: "Review"},
];
export function ControlledVertical() {
const [step, setStep] = React.useState(1);
return (
{steps.map((s) => (
{s.title}{s.description}
))}
);
}
```
### Custom Color
Override the `--stepper-active-color`, `--stepper-complete-color`, and `--stepper-complete-fg` CSS variables via the `style` prop to recolor the active and completed states.
### Custom Color Vertical
### Custom Completed Icon
Use the `` render function to swap the default checkmark for your own icon on completed steps.
### Display Only
Pass `currentStep` without `onStepChange` to render a non-interactive, read-only stepper.
### Dynamic Icon
Render a `` for every status, including completed steps.
### Render Function
Map over your data to render steps declaratively — indexes and the last-step state are resolved automatically.
### Package Tracking
### Free Trial Timeline
Pass an explicit `progress` value (0–1) to `` to render partially filled connectors.
### Onboarding Timeline
### Animated Entrance
By default the stepper renders settled and only animates on interaction (the active step pops with a soft ring and completed steps draw their checkmark when you move between steps). Set `animateOnMount` to play a subtle staggered entrance when the stepper first appears — ideal for landing and onboarding pages. All motion respects the user's reduced-motion preference.
```tsx
"use client";
import {Button, Stepper} from "@darkcode-ui/react";
import React from "react";
const steps = ["Account", "Profile", "Review", "Done"];
export function AnimatedEntrance() {
const [replayKey, setReplayKey] = React.useState(0);
return (
{steps.map((title) => (
{title}
))}
);
}
```
## Related Components
- **ProgressBar**: Shows determinate or indeterminate progress of an operation
- **ProgressCircle**: Circular progress indicator for operations
- **Tabs**: Organize content into tabbed views
## Styling
### CSS Classes
The Stepper component uses these CSS classes:
#### Base & Size Classes
- `.stepper` - Base root container (`ol` element)
- `.stepper--sm` - Small size (22px indicator)
- `.stepper--md` - Medium size (28px indicator, default)
- `.stepper--lg` - Large size (36px indicator)
#### Orientation Classes
- `.stepper--horizontal` - Horizontal layout (default)
- `.stepper--vertical` - Vertical layout
#### Element Classes
- `.stepper__step` - Individual step wrapper (`li` element)
- `.stepper__step-button` - Interactive button (or static wrapper) inside each step
- `.stepper__indicator` - Circle badge showing the step number, icon, or checkmark
- `.stepper__icon` - Icon wrapper inside the indicator
- `.stepper__content` - Wrapper for the title and description
- `.stepper__title` - Step title text
- `.stepper__description` - Step description text
- `.stepper__separator` - Connector line container between steps
- `.stepper__separator-track` - Background rail of the separator
- `.stepper__separator-fill` - Colored progress overlay inside the track
#### Data Attributes
- `[data-status="inactive" | "active" | "complete"]` - Step status, set on `.stepper__step` and `.stepper__indicator`
- `[data-clickable="true"]` - Marks an interactive step button
- `[data-complete]` - Set on a fully filled separator track
### CSS Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `--stepper-indicator-size` | `28px` (md) | Size of the indicator circle |
| `--stepper-separator-size` | `2px` | Thickness of the separator line |
| `--stepper-vertical-gap` | `16px` (md) | Gap between vertical steps |
| `--stepper-active-color` | `var(--accent)` | Color of the active step |
| `--stepper-complete-color` | `var(--accent)` | Color of completed steps |
| `--stepper-complete-fg` | `var(--accent-foreground)` | Foreground color of the completed indicator |
| `--stepper-inactive-border` | `var(--border)` | Border color of the inactive indicator |
| `--stepper-inactive-fg` | `var(--muted)` | Text color of the inactive indicator |
| `--stepper-separator-progress` | `0` | Progress value (0–1) controlling the separator fill |
## API Reference
### Stepper
The root component. Renders an `ol` element and tracks step progress. Also supports all native `ol` HTML attributes.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size variant |
| `currentStep` | `number` | - | The current active step index (controlled) |
| `defaultStep` | `number` | `0` | The initial step index (uncontrolled) |
| `onStepChange` | `(step: number) => void` | - | Called when a step is clicked; makes steps interactive when provided |
| `animateOnMount` | `boolean` | `false` | Play a subtle staggered entrance animation when the stepper first mounts |
| `className` | `string` | - | Additional CSS classes |
### Stepper.Step
A single step wrapper. Renders an `li` element and provides step context to its children. Also supports all native `li` HTML attributes.
### Stepper.Indicator
The circle badge showing the step number, icon, or checkmark. Defaults to the step number for inactive/active steps and an animated checkmark for completed steps.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode \| ((state: { index: number; status: StepperStatus; isLast: boolean }) => ReactNode)` | - | Custom content overriding the default number/checkmark. Returning nullish from the render function falls back to the default |
| `className` | `string` | - | Additional CSS classes |
### Stepper.Content
Flex wrapper for the title and description. Renders a `span` and supports all native `span` HTML attributes.
### Stepper.Title
Step title text. Renders a `span` and supports all native `span` HTML attributes.
### Stepper.Description
Step description text. Renders a `span` and supports all native `span` HTML attributes.
### Stepper.Icon
Icon wrapper rendered inside the indicator. Renders a `span` and supports all native `span` HTML attributes.
### Stepper.Separator
Connector line between steps. Automatically hidden on the last step. Renders a `div` and supports all native `div` HTML attributes.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `progress` | `number` | - | Explicit progress value (0–1). Auto-computed from the step status when omitted |
| `force` | `boolean` | `false` | Force rendering even on the last step |
### useStepperStep
Hook to access the per-step context from any descendant of `Stepper.Step`.
| Property | Type | Description |
|----------|------|-------------|
| `index` | `number` | Zero-based step index |
| `status` | `"inactive" \| "active" \| "complete"` | Current step status |
| `isLast` | `boolean` | Whether this is the last step |