Stepper
Multi-step progress indicator with horizontal/vertical layout, clickable navigation, and step numbers.
import { Stepper } from "phoundry-ui";Horizontal with Navigation
Loading interactive example…
View source
<script lang="ts"> import { Stepper } from "phoundry-ui"; import { Button } from "phoundry-ui";
const steps = [ { id: "account", label: "Account", description: "Create your account" }, { id: "profile", label: "Profile", description: "Set up your profile" }, { id: "preferences", label: "Preferences", description: "Choose your preferences", }, { id: "review", label: "Review", description: "Confirm and submit" }, ];
let horizontalStep = $state(0);</script>
<Stepper {steps} currentStep={horizontalStep} /><div class="mt-4 flex gap-2"> <Button onclick={() => (horizontalStep = Math.max(0, horizontalStep - 1))} disabled={horizontalStep === 0}>Back</Button > <Button onclick={() => (horizontalStep = Math.min(steps.length - 1, horizontalStep + 1))} disabled={horizontalStep === steps.length - 1} variant="primary">Next</Button ></div><p class="mt-2 text-xs text-txt-tertiary"> Step {horizontalStep + 1} of {steps.length}: {steps[horizontalStep].label}</p>Vertical
Loading interactive example…
View source
<script lang="ts"> import { Stepper } from "phoundry-ui"; import { Button } from "phoundry-ui";
const steps = [ { id: "account", label: "Account", description: "Create your account" }, { id: "profile", label: "Profile", description: "Set up your profile" }, { id: "preferences", label: "Preferences", description: "Choose your preferences", }, { id: "review", label: "Review", description: "Confirm and submit" }, ];
let verticalStep = $state(0);</script>
<div class="max-w-xs"> <Stepper {steps} currentStep={verticalStep} orientation="vertical" /></div><div class="mt-4 flex gap-2"> <Button size="sm" onclick={() => (verticalStep = Math.max(0, verticalStep - 1))} disabled={verticalStep === 0}>Back</Button > <Button size="sm" onclick={() => (verticalStep = Math.min(steps.length - 1, verticalStep + 1))} disabled={verticalStep === steps.length - 1} variant="primary">Next</Button ></div>Icons in indicators
Loading interactive example…
View source
<script lang="ts"> import { Stepper } from "phoundry-ui"; import { Button } from "phoundry-ui";
const steps = [ { id: "account", label: "Account", description: "Create your account" }, { id: "profile", label: "Profile", description: "Set up your profile" }, { id: "preferences", label: "Preferences", description: "Choose your preferences", }, { id: "review", label: "Review", description: "Confirm and submit" }, ];
let iconStep = $state(0);
const iconSteps = [ { id: "upload", label: "Upload", icon: "carbon:upload", description: "Pick a file", }, { id: "review", label: "Review", icon: "carbon:view", description: "Check details", }, { id: "finish", label: "Finish", icon: "carbon:checkmark", description: "Submit", }, ];</script>
<p class="mb-2 text-xs text-txt-secondary"> Pass <code>icon</code> on each <code>StepperStep</code>; disable numeric badges with the <code>showNumbers</code> prop when they clutter compact layouts.</p><Stepper steps={iconSteps} currentStep={iconStep} showNumbers={false} /><div class="mt-3 flex gap-2"> <Button size="sm" onclick={() => (iconStep = Math.max(0, iconStep - 1))} disabled={iconStep === 0}>Back</Button > <Button size="sm" variant="primary" onclick={() => (iconStep = Math.min(iconSteps.length - 1, iconStep + 1))} disabled={iconStep === iconSteps.length - 1}>Next</Button ></div>With Numbers & Clickable
Loading interactive example…
View source
<script lang="ts"> import { Stepper } from "phoundry-ui";
const steps = [ { id: "account", label: "Account", description: "Create your account" }, { id: "profile", label: "Profile", description: "Set up your profile" }, { id: "preferences", label: "Preferences", description: "Choose your preferences", }, { id: "review", label: "Review", description: "Confirm and submit" }, ];
let numberedStep = $state(1);</script>
<Stepper {steps} currentStep={numberedStep} showNumbers clickable onstepchange={(i: number) => (numberedStep = i)}/><p class="mt-2 text-xs text-txt-tertiary">Click any step to navigate.</p>API
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
stepsrequired | StepperStep[] | — | Array of step definitions. |
currentSteprequired | number | — | Zero-based index of the active step. |
clickable | boolean | false | Allow clicking steps to navigate. |
onstepchange | (stepIndex: number) => void | — | Called when a clickable step is clicked. |
orientation | "horizontal" | "vertical" | 'horizontal' | Layout direction. |
showNumbers | boolean | true | Show numeric badges for upcoming steps; completed steps still show the check icon. |
class | string | '' | Additional CSS classes. |
step | Snippet<[step: StepperStep, index: number, status: "completed" | "current" | "upcoming"]> | — | Custom snippet for rendering each step indicator. |
StepperStep
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
idrequired | string | — | Unique step identifier. |
labelrequired | string | — | Step label text. |
description | string | — | Optional description below the label. |
icon | string | — | Iconify icon for the step indicator. |
optional | boolean | — | Mark step as optional. |
Usage tips
- Use
clickablewithonstepchangefor wizard UIs where users can jump between completed steps. - Mark optional steps with
optional: trueto display an “Optional” label. - Use the
stepsnippet prop for fully custom step indicators when icons + labels are not enough. clickablerequiresonstepchange- clicks on non-current steps invoke the handler.- Vertical orientation works well in sidebars or narrow containers.
CSS styling
.ph-stepper is the stable identification hook for Stepper. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.
Orientation and step status drive CSS. The numbered indicator uses --ph-comp-h-md; step navigation and custom snippets retain their contracts.
Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.