Stepper

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

Edit on GitHubEditllms.txt

Client Only

Installation

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

Required Packages(2 packages)

pnpm add motion @emotion/is-prop-valid

Usage

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 (
    <Stepper activeStep={active} onStepClick={setActive}>
      {steps.map((step, i) => (
        <Stepper.Step
          key={i}
          label={step.label}
          description={step.description}
        />
      ))}
    </Stepper>
  );
}

Vertical Orientation

<Stepper activeStep={1} orientation="vertical">
  <Stepper.Step label="Step 1" />
  <Stepper.Step label="Step 2" />
  <Stepper.Step label="Step 3" />
</Stepper>

With Custom Icons & Status

<Stepper activeStep={1}>
  <Stepper.Step label="Upload" icon={<UploadIcon />} status="finish" />
  <Stepper.Step label="Process" status="process" />
  <Stepper.Step label="Review" status="error" />
  <Stepper.Step label="Publish" status="wait" />
</Stepper>

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

StepperSize

'sm' | 'default' | 'lg'

StepperOrientation

'horizontal' | 'vertical'

Credits

shadcn-ui/ui

Stepper

Credits

On this page