Stepper

A multi-step form component for breaking down complex processes into manageable steps. The component handles state management and provides a programmatic API for navigation.

Installation

npx @zizigy/capsule add Stepper

Usage

Basic Stepper

The Stepper provides the structure and state management. You'll need to add your own visual styles for step indicators, lines, and animations.

<capsule-stepper current-step="1">
  <capsule-stepper-steps>
    <capsule-stepper-step>Account</capsule-stepper-step>
    <capsule-stepper-step>Profile</capsule-stepper-step>
    <capsule-stepper-step>Review</capsule-stepper-step>
  </capsule-stepper-steps>
  <capsule-stepper-panels>
    <capsule-stepper-panel>...</capsule-stepper-panel>
    <capsule-stepper-panel>...</capsule-stepper-panel>
    <capsule-stepper-panel>...</capsule-stepper-panel>
  </capsule-stepper-panels>
</capsule-stepper>

Navigation

const stepper = document.querySelector('capsule-stepper');

// Navigate programmatically
stepper.next(); // Go to next step
stepper.previous(); // Go to previous step
stepper.setStep(3); // Jump to specific step
stepper.first(); // Go to first step
stepper.last(); // Go to last step
stepper.reset(); // Reset to first step

Orientation

<capsule-stepper
  current-step="1"
  orientation="vertical"
>
  ...
</capsule-stepper>

Animation

<capsule-stepper-panels animation="x">
  <!-- Horizontal slide animation -->
</capsule-stepper-panels>

<capsule-stepper-panels animation="y">
  <!-- Vertical slide animation -->
</capsule-stepper-panels>

Components

The Stepper component consists of several sub-components:

capsule-stepper

Main container that manages the current step and provides navigation API.

Attribute	Type	Default	Description
current-step	number	1	Current active step (1-indexed)
orientation	string	-	Layout direction (vertical, horizontal)

Orientation Values

• vertical — Steps arranged vertically
• horizontal — Steps arranged horizontally (default if not specified)

capsule-stepper-steps

Container for step indicators. No attributes.

capsule-stepper-step

Individual step indicator.

Attribute	Type	Description
status	string	Step status (active, completed, inactive)

Status Values

• active — Currently active step
• completed — Step has been completed
• inactive — Step not yet reached

capsule-stepper-panels

Container for panel content.

Attribute	Type	Default	Description
animation	string	-	Animation type (x, y, none)
orientation	string	-	Direction of panels (vertical, horizontal)

Animation Values

• x — Horizontal slide animation (default for horizontal stepper)
• y — Vertical slide animation (default for vertical stepper)
• none — No animation

Orientation Values

• vertical — Panels arranged vertically
• horizontal — Panels arranged horizontally

capsule-stepper-panel

Individual content panel.

Attribute	Type	Description
status	string	Panel status (active, inactive)

Status Values

• active — Currently visible panel
• inactive — Hidden panel

Attributes

All attributes are described in the Components section above. Here are additional details:

status attribute values

For capsule-stepper-step:

• active — Currently active step
• completed — Step that has been completed
• inactive — Step not yet reached

For capsule-stepper-panel:

• active — Currently visible panel
• inactive — Hidden panel

animation attribute values

For capsule-stepper-panels:

• x — Horizontal slide animation
• y — Vertical slide animation
• none — No animation

orientation attribute values

For capsule-stepper:

• vertical — Vertical layout

API Methods

Navigation

Method	Returns	Description
next()	boolean	Go to next step
previous()	boolean	Go to previous step
setStep(n)	void	Jump to specific step (1-indexed)
first()	void	Go to first step
last()	void	Go to last step
reset()	void	Reset to first step

State Checks

Method	Returns	Description
canGoNext()	boolean	Can navigate to next step
canGoPrevious()	boolean	Can navigate to previous step

Getters

Property	Returns	Description
currentStep	number	Current step number (1-indexed)
totalSteps	number	Total number of steps
status	object	Status object with current step info

Events

change

Dispatched when the current step changes.

stepper.addEventListener('change', (e) => {
  console.log(e.detail); // { current, total, isFirst, isLast, progress }
});

Styling

The component provides minimal CSS for layout only. You need to style:

• Step indicators: Circles, numbers, icons, checkmarks
• Connector lines: Lines between steps
• Panel transitions: Custom animations if needed
• State variations: Active, completed, inactive styles

Example CSS structure:

/* Your custom styles */
capsule-stepper-step[status='active'] {
  color: blue;
}

capsule-stepper-step[status='completed'] {
  color: green;
}

capsule-stepper-step[status='inactive'] {
  color: gray;
}

Accessibility

• ✅ Automatic ARIA attributes for step status
• ✅ Keyboard navigation support
• ✅ Focus management
• ✅ Semantic structure for screen readers