Stepper

The Stepper component provides a multi-step progress indicator for wizard-like workflows. It shows the current step, completed steps, and upcoming steps with visual connectors.

Installation

npm install @duskmoon-dev/el-stepper

Usage

import '@duskmoon-dev/el-stepper/register';
<el-dm-stepper id="my-stepper" current="1"></el-dm-stepper>

<script>
  const stepper = document.getElementById('my-stepper');
  stepper.steps = [
    { label: 'Account', description: 'Create your account' },
    { label: 'Profile', description: 'Add profile details' },
    { label: 'Review', description: 'Review and submit' }
  ];
</script>

Live Demo

Stepper Demo

PreviousNext

Properties

PropertyTypeDefaultDescription
stepsStepData[][]Array of step objects with label, description, and optional icon
currentnumber0Current step index (0-based)
orientation'horizontal' | 'vertical''horizontal'Layout orientation
color'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'error' | 'info''primary'Stepper color theme
clickablebooleanfalseWhether steps are clickable for navigation

StepData Interface

interface StepData {
  label: string;       // Required: Step label text
  description?: string; // Optional: Step description
  icon?: string;       // Optional: Icon (text, emoji, or HTML)
}

Orientations

Horizontal (default)

<el-dm-stepper orientation="horizontal"></el-dm-stepper>

Vertical

<el-dm-stepper orientation="vertical"></el-dm-stepper>

Colors

<el-dm-stepper color="primary"></el-dm-stepper>
<el-dm-stepper color="secondary"></el-dm-stepper>
<el-dm-stepper color="success"></el-dm-stepper>
<el-dm-stepper color="warning"></el-dm-stepper>
<el-dm-stepper color="error"></el-dm-stepper>
<el-dm-stepper color="info"></el-dm-stepper>

Clickable Steps

Enable step navigation by clicking:

<el-dm-stepper clickable></el-dm-stepper>

Custom Icons

Steps can include custom icons:

stepper.steps = [
  { label: 'Cart', icon: '🛒' },
  { label: 'Shipping', icon: '📦' },
  { label: 'Payment', icon: '💳' },
  { label: 'Complete', icon: '✅' }
];

Events

EventDetailDescription
change{ current: number, previous: number }Fired when step changes via click (when clickable is true)

Event Handling

const stepper = document.querySelector('el-dm-stepper');
stepper.addEventListener('change', (e) => {
  console.log('Step changed from', e.detail.previous, 'to', e.detail.current);
});

CSS Parts

PartDescription
stepperThe stepper container
stepIndividual step wrapper
indicatorThe step number/icon circle
contentThe step label and description wrapper
labelThe step label text
descriptionThe step description text
connectorThe connector line between steps

Styling with CSS Parts

el-dm-stepper::part(indicator) {
  width: 2.5rem;
  height: 2.5rem;
  font-size: 1rem;
}

el-dm-stepper::part(label) {
  font-size: 1rem;
}

el-dm-stepper::part(connector) {
  height: 3px;
}

Individual Step Element

For more control, use el-dm-step elements:

<el-dm-step label="Step 1" description="First step" status="completed" step-number="1"></el-dm-step>
<el-dm-step label="Step 2" description="Current step" status="current" step-number="2"></el-dm-step>
<el-dm-step label="Step 3" description="Upcoming step" status="upcoming" step-number="3"></el-dm-step>

Step Element Properties

PropertyTypeDefaultDescription
labelstring-Step label text
descriptionstring-Optional description text
iconstring-Optional icon (text/emoji/html)
status'completed' | 'current' | 'upcoming''upcoming'Step status
step-numbernumber1Step number to display
orientation'horizontal' | 'vertical''horizontal'Layout orientation
colorstring'primary'Step color

Step Element Slots

SlotDescription
defaultCustom step content
iconCustom icon content

Accessibility

  • Uses role="navigation" with aria-label="Progress steps"
  • Step states are visually distinct for completed, current, and upcoming
  • Clickable steps can be focused and activated with keyboard