Steps

Progress indicators for multi-stage flows. Use visible labels for task-heavy screens, compact numbered steps for tight layouts, and HTMX swaps when the server owns the current step.

completedCreate an account
2Select a plan
3Checkout
4Get started

Usage Example

@steps.Steps(steps.Config{
    ShowLabels: true,
    AriaLabel:  "registration progress",
    Steps: []steps.Step{
        {Label: "Create an account", Status: steps.StatusCompleted},
        {Label: "Select a plan", Status: steps.StatusCurrent},
        {Label: "Checkout", Status: steps.StatusUpcoming},
        {Label: "Get started", Status: steps.StatusUpcoming},
    },
})

Default Steps

Horizontal progress without visible labels. Matches PenguinUI default number-only flow.

completed
2
3
4

Default Steps

@steps.Steps(steps.Config{
    AriaLabel: "registration progress",
    Steps: []steps.Step{
        {AriaLabel: "Create an account", Status: steps.StatusCompleted},
        {AriaLabel: "Select a plan", Status: steps.StatusCurrent},
        {AriaLabel: "Checkout", Status: steps.StatusUpcoming},
        {AriaLabel: "Get started", Status: steps.StatusUpcoming},
    },
})

HTMX State Swap

Server owns state. Buttons swap the whole progress block with prev/next states, so no Alpine local state gets stranded or reset incorrectly.

completedCreate an account
2Select a plan
3Checkout
4Get started

Current server state: step 2 of 4.

HTMX State Swap

<div id="steps-demo-shell">
    @components.StepsHTMXFlow(2)
</div>

// Server handler returns @components.StepsHTMXFlow(step)
// Buttons use hx-get + hx-target="#steps-demo-shell" + hx-swap="outerHTML"

Vertical Steps

Vertical flow for tighter sidebars, setup assistants, or stacked onboarding guides.

completed
Create an account
2
Select a plan
3
Checkout
4
Get started

Vertical Steps

@steps.Steps(steps.Config{
    Orientation: steps.OrientationVertical,
    ShowLabels:  true,
    AriaLabel:   "registration progress",
    Steps: []steps.Step{
        {Label: "Create an account", Status: steps.StatusCompleted},
        {Label: "Select a plan", Status: steps.StatusCurrent},
        {Label: "Checkout", Status: steps.StatusUpcoming},
        {Label: "Get started", Status: steps.StatusUpcoming},
    },
})

API Reference

Prop	Type	Default	Description
`ID`	`string`	`""`	Stable root id for HTMX targets, swaps, and tests.
`Steps`	`[]Step`	`nil`	Ordered progress items. Each Step supports ID, Label, AriaLabel, Number, Status, and StepAttrs.
`Orientation`	`Orientation`	`OrientationHorizontal`	Layout direction: "horizontal" or "vertical".
`ShowLabels`	`bool`	`false`	Shows visible labels beside the step indicators.
`AriaLabel`	`string`	`"progress"`	Accessible label for the ordered list.
`LiveRegion`	`bool`	`false`	Announces swapped state changes after HTMX updates.
`RootClass`	`string`	`""`	Extra classes appended to the root ordered list.
`RootAttrs`	`templ.Attributes`	`nil`	Pass-through attributes for root hx-* hooks, data attributes, and test selectors.

Spinner Tooltip