Component proposal: Stepper

[dexterhere]

Component proposal: Stepper

I would like to contribute a new Stepper component to Rust/UI.

Motivation

Rust/UI currently provides components such as Progress, Tabs, Forms and Status indicators, but it does not have a dedicated Stepper for multi-step workflows.

A Stepper would be useful for:

• Account onboarding
• Checkout processes
• Multi-step forms
• Installation flows
• Verification processes
• Project setup wizards

Proposed initial scope

The first version would support:

• Horizontal orientation
• Vertical orientation
• Controlled current-step state
• Completed, active and pending step states
• Optional clickable step triggers
• Disabled steps
• Custom labels and descriptions
• Custom indicator content
• Keyboard-accessible native buttons
• aria-current="step" for the active step
• Tailwind CSS styling
• Pure Rust and Leptos implementation without JavaScript

Proposed component anatomy

<Stepper value=current_step>
    <StepperItem step=0>
        <StepperTrigger>
            <StepperIndicator />
            <StepperTitle>"Account"</StepperTitle>
            <StepperDescription>
                "Create your account"
            </StepperDescription>
        </StepperTrigger>
        <StepperSeparator />
    </StepperItem>

    <StepperItem step=1>
        <StepperTrigger>
            <StepperIndicator />
            <StepperTitle>"Profile"</StepperTitle>
            <StepperDescription>
                "Complete your profile"
            </StepperDescription>
        </StepperTrigger>
    </StepperItem>
</Stepper>

The internal step state would be calculated as:

• step < current_step → completed
• step == current_step → active
• step > current_step → pending

Possible files

app_crates/registry/src/ui/stepper.rs
app_crates/registry/src/demos/demo_stepper.rs
app_crates/registry/src/demos/demo_stepper_controlled.rs
app_crates/registry/src/demos/demo_stepper_vertical.rs
public/docs/components/stepper.md

I would first implement the basic controlled component and orientations. Advanced features such as validation states, optional steps, error states and step content panels could be added separately.

Would this component and scope be suitable for Rust/UI? I would also appreciate guidance on the preferred controlled-state API.

Note: The contribution guide recommends discussing new component ideas through GitHub Discussions. However, the Discussions link currently returns a 404 error. I am submitting this proposal here instead so the component scope and API can be reviewed before I begin the full implementation.

[max-wells]

Thanks for the detailed proposal. Scope looks good, and the anatomy (Stepper / StepperItem / StepperTrigger / StepperIndicator / StepperSeparator) fits how we structure compound components here. A few things to align on before you start implementing:

References

Feel free to look at existing stepper implementations for ideas, but keep the shadcn-like way of doing things we use here (see below). A few worth checking:

• francozeta/stepper: good composition/anatomy conventions, close to what you proposed.
• damianricobelli/stepperize (packages/core/src/utils.ts): clean step model (indexOf/next/prev/neighbors, getStepStatus).
• Johann-S/bs-stepper (src/js/index.js): minimal next()/previous()/to(n)/reset() control flow.

Match our conventions

1. Enums, not strings, for variants/state. See tabs.rs:

   #[derive(Clone, Copy, PartialEq, Eq, Default)]
   pub enum TabsOrientation {
       #[default]
       Horizontal,
       Vertical,
   }

   Do the same for orientation and step state, e.g.:

   #[derive(Clone, Copy, PartialEq, Eq)]
   pub enum StepState {
       Completed,
       Active,
       Pending,
       Disabled,
   }

   If the trigger/indicator need Tailwind variant classes (not just structural state), use the variants! macro like button.rs does, rather than hand-rolled tw_merge! branching.

2. Extract the logic into a hook. Don't inline the index/navigation logic in the Stepper component body — pull it into app_crates/registry/src/hooks/use_stepper.rs, following the same shape as use_pagination.rs: a plain function returning a context struct of signals/callbacks, e.g.:

   #[derive(Clone)]
   pub struct StepperContext {
       pub current_index: RwSignal<usize>,
       pub total_steps: usize,
       pub can_go_prev: Signal<bool>,
       pub can_go_next: Signal<bool>,
       pub go_next: Callback<(), ()>,
       pub go_prev: Callback<(), ()>,
       pub go_to: Callback<usize, ()>,
       pub step_state: Callback<usize, StepState>,
   }
   
   pub fn use_stepper(total_steps: usize, default_index: usize) -> StepperContext

   Stepper provides this via provide_context, and StepperItem / StepperTrigger consume it via use_context, same as TabsCtx in tabs.rs. Keeps the components themselves dumb/presentational.

Re: the Discussions 404 — thanks for flagging, we'll get that fixed separately.

Go ahead and start with the controlled component + both orientations as you proposed; happy to review a draft PR before you build out the advanced states.