SutraUI.Stepper (Sutra UI v0.4.0)

A progress indicator for multi-step workflows.

Stepper provides the chrome — numbered markers, connector lines, and state styling. You define what each step looks like inside the :step slot. Step states auto-compute from the current index, so you rarely set them by hand.

Examples

# Basic — states auto-compute from current
<.stepper current={2}>
  <:step>
    <h4>Profile</h4>
    <p>Tell us about yourself</p>
  </:step>
  <:step>
    <h4>Workspace</h4>
    <p>Configure defaults</p>
  </:step>
  <:step>
    <h4>Invite</h4>
    <p>Bring in teammates</p>
  </:step>
</.stepper>

# Vertical orientation for side panels
<.stepper current={3} orientation="vertical">
  <:step><h4>Account</h4></:step>
  <:step><h4>Team</h4></:step>
  <:step><h4>Billing</h4></:step>
  <:step><h4>Launch</h4></:step>
</.stepper>

# Clickable steps — emit an event when a marker is clicked
<.stepper current={@current_step} select_event="jump_to_step">
  <:step value="profile"><h4>Profile</h4></:step>
  <:step value="workspace"><h4>Workspace</h4></:step>
  <:step value="invite"><h4>Invite</h4></:step>
</.stepper>

# Error state — pass an errors map keyed by step index
<.stepper current={3} errors={%{3 => "Card declined"}}>
  <:step><h4>Select plan</h4></:step>
  <:step><h4>Payment</h4></:step>
  <:step><h4>Confirm</h4></:step>
</.stepper>

Step States

States auto-compute from current (1-based):

Condition	State
index < current	`complete` (checkmark)
index == current	`current` (highlighted)
index > current	`pending` (muted)
errors[index] present	`error` (overrides auto-state)

Override any step's state explicitly with the state slot attr.

Attributes

current - 1-based index of the active step. 0 means none active.
errors - Map of step index → error message. Auto-marks those steps as error.
orientation - horizontal, vertical, or responsive (vertical on mobile, horizontal on desktop). Defaults to horizontal.
variant - default (solid markers) or outline (bordered markers).
select_event - When set, markers become buttons that emit this event with phx-value-step set to the step's value.
class - Additional CSS classes.

Slot Attributes

The :step slot accepts:

state - Override the auto-computed state: complete, current, pending, error.
icon - Custom text/emoji for the marker — overrides the number and auto-state icons.
value - Step value, emitted as phx-value-step when select_event is set.

Accessibility

Uses an ordered list (<ol>) to convey sequence.
The active step sets aria-current="step".
When select_event is set, markers render as <button> elements; otherwise they're non-interactive spans.

Summary

Functions

stepper(assigns)

Functions

stepper(assigns)

Attributes

current (:integer) - One-based index of the active step. 0 means none active. Defaults to 0.
errors (:map) - Map of step index (1-based) → error message. Auto-marks those steps as error. Defaults to %{}.
orientation (:string) - Stepper orientation. Defaults to "horizontal". Must be one of "horizontal", "vertical", or "responsive".
variant (:string) - Visual variant — outline gives bordered markers. Defaults to "default". Must be one of "default", or "outline".
select_event (:string) - When set, markers become buttons that emit this event with phx-value-step. Defaults to nil.
class (:any) - Additional CSS classes. Defaults to nil.
Global attributes are accepted. Additional HTML attributes. Supports all globals plus: ["id", "aria-label"].

Slots

step (required) - Accepts attributes:
- state (:string) - Step state. Defaults to auto-computed from current. Must be one of "complete", "current", "pending", or "error".
- icon (:string) - Custom text/emoji for the marker — overrides number and auto-state icons.
- value (:string) - Step value, emitted as phx-value-step when select_event is set.