Wizard

A multi-step flow the reader works through: configure the instance, connect the database, invite the team, review, go.

Component behaviorCopy link

Wizard renders a multi-step flow with validation, conditional steps, completion state, and ordered navigation. Validation can be asynchronous. Revisiting an earlier step preserves later completion state.

PropsCopy link

StepsCopy link

LabelsCopy link

The piecesCopy link

WizardNav renders a Stepper using wizard steps, statuses, and reachability. Remaining StepperProps are forwarded except for props managed by the wizard.

Steps, values and branchesCopy link

steps is required. Each step has an id and label. content accepts a node or a function receiving the current wizard API.

const steps: WizardStep<Setup>[] = [
  {
    id: "instance",
    label: "Instance",
    group: "Get started", // uppercase heading in the rail
    hint: "Name and public URL", // second line under the label
    description: "Instance identification settings.",
    validate: (values) =>
      values.url.startsWith("https://") || "The base URL has to be https://.",
    content: (api) => (
      <Field label="Base URL" htmlFor="url">
        <Input
          id="url"
          value={api.values.url}
          onChange={(e) => api.setValue("url", e.currentTarget.value)}
        />
      </Field>
    ),
  },
];

Use defaultValues for internal answer state or values with onValuesChange for controlled state. setValue and setValues update either form.

BranchesCopy link

includeWhen controls whether a step is included. Excluded steps do not appear, count toward progress, or block navigation. If the active step becomes excluded, selection moves to the nearest preceding visible step.

{
  id: "connection",
  label: "Connection",
  includeWhen: (values) => values.engine !== "bundled",
  validate: (values) => values.tested || "Run Test connection first.",
  content: (api) => …,
}

ValidationCopy link

validate returns true or undefined for success, false for failure without a message, or a string for failure with a message. Promises show a spinner until settled. Thrown errors fail validation. Error messages appear above the step and mark it as failed in navigation.

ExamplesCopy link

A setup flowCopy link

Seven steps, three groups, one optional, two that come and go. Pick Bundled SQLite and the Connection step leaves the flow; pick Local accounts and the Provider step does.

A short flowCopy link

layout="steps" places step navigation above the content. The default layout places navigation beside the content.

Custom layoutCopy link

useWizard provides the state machine without layout. WizardProvider exposes it to WizardNav, WizardFooter, and WizardSummary.

Keyboard & accessibilityCopy link

• The rail is a nav of buttons; the current step carries aria-current="step" and every item has visually-hidden state text (“Completed”, “Needs attention”).
• Unreachable steps are disabled and excluded from Tab navigation.
• Focus moves to the pane heading on every step change, never on first render.
• ⌘ / Ctrl + Enter advances.
• Each navigation item exposes data-state: current, complete, skipped, error, or upcoming.

ImportCopy link

import {
  Wizard,
  WizardNav,
  WizardFooter,
  WizardSummary,
  WizardProvider,
  useWizard,
} from "@solarius/onset";
import type { WizardStep, WizardApi } from "@solarius/onset";

<Wizard
  steps={steps}
  defaultValues={{ url: "", engine: "postgres" }}
  title="Set up Anchorpoint"
  onFinish={install}
/>;