# Stepper
URL: /docs/web/components/stepper

A multi-step progress indicator with 6 visual variants, horizontal/vertical orientation, animated transitions, and customizable step icons.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import {
  Stepper, Step, type StepperVariant, type StepperOrientation, type StepperSize
} from '@docyrus/ui/components/stepper';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

const STEPS = [
  { label: 'Account', description: 'Create your account' },
  { label: 'Profile', description: 'Set up your profile' },
  { label: 'Review', description: 'Review your details' },
  { label: 'Complete', description: 'All done!' }
];

export function StepperDemo() {
  const [activeStep, setActiveStep] = useState(1);
  const [variant, setVariant] = useState
                  
                    
                    
                    
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Orientation</span>
                
                  
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">alternativeLabel</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">nonLinear</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Error (Step 2)</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      <div className="rounded-lg border border-border p-6">
        
        <div className="mt-6 flex items-center justify-between">
          <button
            type="button"
            className="rounded-md border border-border px-4 py-2 text-sm font-medium transition-colors hover:bg-accent disabled:opacity-50"
            disabled={activeStep === 0}
            onClick={() => setActiveStep(prev => prev - 1)}>
            Back
          </button>
          <span className="text-sm text-muted-foreground">
            Step {activeStep + 1} / {STEPS.length}
          </span>
          {activeStep < STEPS.length - 1 ? (
            <button
              type="button"
              className="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90"
              onClick={() => setActiveStep(prev => prev + 1)}>
              Next
            </button>
          ) : (
            <button
              type="button"
              className="rounded-md border border-border px-4 py-2 text-sm font-medium transition-colors hover:bg-accent"
              onClick={() => setActiveStep(0)}>
              Reset
            </button>
          )}
        </div>
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-stepper
```

**Dependencies:**
- [motion](https://www.npmjs.com/package/motion)
- [@emotion/is-prop-valid](https://www.npmjs.com/package/@emotion/is-prop-valid)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  Stepper,
  useStepperContext
} from '@docyrus/ui/components/stepper';
import type { StepProps } from '@docyrus/ui/components/stepper';

const steps: StepProps[] = [
  { label: 'Account', description: 'Create your account' },
  { label: 'Profile', description: 'Set up your profile' },
  { label: 'Complete', description: 'All done!' }
];

function MyWizard() {
  const [active, setActive] = useState(0);

  return (
    
  );
}
```

### Vertical Orientation

```tsx

```

### With Custom Icons & Status

```tsx

```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Numbered circles with filled background. |
| `outline` | Outlined circles with border. |
| `dots` | Small dots with pulse animation on active step. |
| `dashed` | Dashed connector lines. |
| `gradient` | Gradient-filled indicators. |
| `minimal` | Text-only with subtle indicators. |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small indicators and text. |
| `default` | Standard size. |
| `lg` | Large indicators and text. |

## Components

| Component | Description |
|-----------|-------------|
| `Stepper` | Root component with context provider. Renders the step layout. |
| `Stepper.Step` | Individual step with icon, label, description, and status. |
| `StepConnector` | Line between steps. Animates on completion. |
| `useStepperContext` | Hook to access stepper state (activeStep, variant, size, etc.). |

## API Reference

### Stepper

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `activeStep` | `number` | `0` | Current active step index. |
| `variant` | `'default' \| 'outline' \| 'dots' \| 'dashed' \| 'gradient' \| 'minimal'` | `'default'` | Visual style of the stepper. |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Size of step indicators. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. |
| `nonLinear` | `boolean` | `false` | Allow clicking on any step regardless of order. |
| `alternativeLabel` | `boolean` | `false` | Place labels below indicators instead of beside them. |
| `onStepClick` | `(index: number) => void` | — | Called when a step is clicked. |
| `connector` | `ReactNode` | — | Custom connector component between steps. |
| `className` | `string` | — | Additional CSS classes. |

### Step

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `ReactNode` | — | Step title text. |
| `description` | `ReactNode` | — | Step subtitle/description. |
| `icon` | `ReactNode` | — | Custom step icon. Falls back to step number. |
| `status` | `'wait' \| 'process' \| 'finish' \| 'error'` | — | Manual status override. Auto-determined from `activeStep` if not set. |
| `optional` | `boolean` | — | Mark as optional step. |
| `disabled` | `boolean` | — | Disable click interaction. |

### StepConnector

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `animated` | `boolean` | `true` | Animate the connector fill on completion. |

## Type Reference

### StepStatus

`'wait'` | `'process'` | `'finish'` | `'error'`

### StepperVariant

`'default'` | `'outline'` | `'dots'` | `'dashed'` | `'gradient'` | `'minimal'`

### StepperSize

`'sm'` | `'default'` | `'lg'`

### StepperOrientation

`'horizontal'` | `'vertical'`