Stepper

catnip-stepper communicates progress through a finite, ordered process. It supports horizontal and vertical layouts, optional step names, completed connectors, four semantic intents, an independent active state, and opt-in step navigation.

The component owns the ordered-list structure, current-step semantics, marker and connector presentation, keyboard-operable buttons in interactive mode, and the step-click request event. The consumer owns process state, validation messages, whether navigation is permitted, and updating the steps data after a request.

Live example

Basic use

Pass steps as a JavaScript property. Each item can provide value, stepName, intent, activeStep, disabled, and ariaLabel:

<catnip-stepper
  .steps="[
    { value: 'account', stepName: 'Account', intent: 'completed', activeStep: false },
    { value: 'identity', stepName: 'Identity', intent: 'default', activeStep: true },
    { value: 'review', stepName: 'Review', intent: 'default' }
  ]"
  .showStepsName="true"
  aria-label="Account setup progress"
/>

Plain HTML can use a JSON steps attribute. Framework consumers should prefer a property binding so arrays are not stringified accidentally.

Layout and names

• Step names are hidden by default. Set showStepsName to true to display them. When names are shown, every step must provide a non-empty stepName; otherwise the component logs a warning in every environment.
• orientation="horizontal" is the default. stepNamePosition="horizontal" places a shown name beside the marker; vertical places it below the marker.
• Horizontal layout preserves full names, markers, and connectors whenever they fit. When the complete sequence no longer fits, labelled previous/next icon buttons appear instead of progressively shortening every name. They move the visible range by one step and replace reliance on an exposed scrollbar.
• Only an individual name that exceeds its maximum step width is truncated with an ellipsis. Its complete value remains in the native title tooltip and in the accessible step label.
• orientation="vertical" always places a name beside its marker. A development warning explains that stepNamePosition="vertical" is ignored in this orientation.
• Connectors preserve the design-system spacing between adjacent markers in vertical layouts and in horizontal layouts without visible names.
• When showStepsName is false, names remain available to assistive technologies but only the numbered or intent marker is rendered. Leave stepNamePosition unset; the docs playground exposes this omitted value as (none). An explicitly selected position produces a development warning because it has no visual effect in this mode.

Interactive navigation

The default stepper is read-only progress content. Set interactive only when users are allowed to move among steps. Enabled steps then become native buttons:

<catnip-stepper .steps="steps" .interactive="true" .showStepsName="true" aria-label="Checkout steps" @step-click="onStepClick" />

Read event.detail[0] in Vue custom-element usage; it contains { index, value, step, steps }. The component immediately marks the clicked item active and clears active state from every other item. Use the emitted steps array to synchronize controlled application state, then validate, navigate, or reveal the requested content. Disabled steps use the native disabled state and do not emit.

Accessibility

• Steps are a native <ol>, preserving order and list position for assistive technologies.
• The item with activeStep: true receives aria-current="step". Active state is independent from intent, so a current step can remain visually and semantically completed, warning, or danger.
• A development warning is emitted when more than one item supplies activeStep: true; the component deterministically uses the first one.
• Static progress is exposed as a labelled group. Interactive progress is a labelled navigation landmark containing native <button> elements, so Enter, Space, Tab, focus indication, and disabled behavior come from the platform.
• Overflow controls are native icon-only buttons named “Show previous steps” and “Show next steps”. Their disabled state communicates the beginning and end of the horizontal list.
• Completed, warning, danger, and current states include screen-reader text and visible shape/icon changes; state is not conveyed by colour alone.
• Use a specific ariaLabel when more than one stepper or navigation landmark is present. Use per-step ariaLabel only when the visible name does not describe the destination sufficiently.
• Keep the validation explanation beside the affected form control and connect it with aria-describedby. The stepper indicates that a step has a warning or error; it does not replace the actionable message.