Skip to content

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
horizontal-with-navigation.svelte
<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
vertical.svelte
<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
icons-in-indicators.svelte
<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
with-numbers-clickable.svelte
<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

NameTypeDefaultDescription
stepsrequiredStepperStep[]—Array of step definitions.
currentSteprequirednumber—Zero-based index of the active step.
clickablebooleanfalseAllow clicking steps to navigate.
onstepchange(stepIndex: number) => void—Called when a clickable step is clicked.
orientation"horizontal" | "vertical"'horizontal'Layout direction.
showNumbersbooleantrueShow numeric badges for upcoming steps; completed steps still show the check icon.
classstring''Additional CSS classes.
stepSnippet<[step: StepperStep, index: number, status: "completed" | "current" | "upcoming"]>—Custom snippet for rendering each step indicator.

StepperStep

From phoundry-ui@0.4.21

NameTypeDefaultDescription
idrequiredstring—Unique step identifier.
labelrequiredstring—Step label text.
descriptionstring—Optional description below the label.
iconstring—Iconify icon for the step indicator.
optionalboolean—Mark step as optional.

Usage tips

  • Use clickable with onstepchange for wizard UIs where users can jump between completed steps.
  • Mark optional steps with optional: true to display an “Optional” label.
  • Use the step snippet prop for fully custom step indicators when icons + labels are not enough.
  • clickable requires onstepchange - 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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.