Wizard

Introduction

Wizard is a schema layout that shows one labeled step at a time. Each step is a chunk of fields (or nested layouts). Alpine keeps the current step in x-data; Back / Continue (and optional Skip) move between them without a route change.

Reach for it on onboarding, multi-page creates, and any form that is too long for a single scroll.

Basic wizard

Steps as dicts (label + schema) or as (label, components) tuples.

from almasix.orbit.forms import TextInput, Textarea
from almasix.orbit.schemas import Wizard

Wizard.make("onboard")
    .steps(
        {"label": "Account", "schema": [TextInput.make("email").email().required()]},
        {"label": "Profile", "schema": [TextInput.make("name").required()]},
    )
    .start_step(0)

Orbit Basic wizard (light)

Orbit Basic wizard (dark)

.start_step(index) picks which pane is visible on first paint (clamped to the last step).

Step descriptions

Dict steps may include description. It renders under the step title inside the pane.

Wizard.make("onboard").steps(
    {
        "label": "Account",
        "description": "We will send a confirmation to this address.",
        "schema": [TextInput.make("email").email().required()],
    },
    {
        "label": "Profile",
        "description": "Shown on your public author page.",
        "schema": [TextInput.make("name").required(), Textarea.make("bio")],
    },
)

Orbit Wizard with descriptions (light)

Orbit Wizard with descriptions (dark)

Skippable steps

.skippable() adds a Skip link that advances to the next step without validating the current pane. Validation still runs when the wrapping form submits.

Wizard.make("onboard")
    .skippable()
    .steps(
        {"label": "Account", "schema": [TextInput.make("email").required()]},
        {"label": "Optional bio", "schema": [Textarea.make("bio")]},
    )

Orbit Skippable wizard (light)

Orbit Skippable wizard (dark)

The nav buttons on the left jump to any step (@click="step = n"). Continue is disabled on the last step; Back is disabled on the first.

API cheat sheet

Method	Role
`.steps(...)`	Dicts (`label` / `id`, `schema` / `components`, optional `description`) or `(label, components)` tuples
`.start_step(index)`	Zero-based first pane
`.skippable()`	Show Skip in the footer

All fields across every step are still children of the parent form — dehydrate and validate the whole schema on submit.

Closures on .visible() hide a wizard (or nested fields) entirely — see Form closures.