All components (204)

Step wizard

Navigation · Wizard · .amset-wizard

What it is and when to use it

A long form split into steps (checkout, creating a customer, initial setup): the Steps row at the top, the current step in its panel and the previous and next buttons below.

When to use it

When the form does not fit on one screen and is better understood in parts that make sense on their own.
onExit on each step to validate it: if it returns false (or a promise that ends in false) it does not advance. While waiting, the button stays busy and does not accept double submissions.
onFinish for what happens on leaving the last step: there the button says finishText ("Finish").
If onExit or onFinish fail (they throw or their promise is rejected), the step does not advance, errorText appears next to the buttons and the error goes to onError with the step's key (without onError, to the console, with the process and the step).
headingLevel depending on where it goes: the title of each step is an h3 by default; below a bare h1, 2.
index and onStepChange to drive the step from outside; previousText and nextText change the text of the buttons.

When not to

For a short form: a single one, without steps, gets filled in faster.
To show how far something has got without filling anything in (an order, a shipment): Steps.
For sections that can be filled in in any order: Tabs or Accordion.

Keyboard: Tab goes through the step row, the step content and the buttons. When the step changes, the focus goes to the panel of the new step: the next Tab enters its fields. In the row only what has already been visited can be pressed; what comes later is disabled.

Accessibility: it is a section with a name (label); the row is a list with the current step marked, called "Steps: " and the label as is (or whatever stepsLabel says), and the panel is a group named by the step's title, which is a heading of the level headingLevel says. The change is announced ("Step 2 of 3: Shipping address", with the numbers in the language) in a role="status". While validating, the button says "Checking". A failure is stated in a role="alert", which is announced immediately, and the focus stays on the button so you can try again.

Context: it goes inside LocaleProvider (or AmsetProvider), which decides how the numbers in the count are written.

Fine-tuning: CSS variables --amset-wizard-*: -gap. The size changes the gap between the steps, the content and the buttons.

What it looks like

Data

Name, email and phone.

<Wizard
  label="Customer registration"
  steps={[
    { key: 'datos', title: 'Data', content: <Datos /> },
    { key: 'pago', title: 'Payment', content: <Pago /> },
  ]}
/>

Props

Import it with import { Wizard } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`label`required	`string`	Name of the whole process: "Checkout", "Customer registration".
`steps`required	`readonly WizardStep[]`	—
`className`	`string`	Merged with the library classes; it does not replace them.
`errorText`	`string`	What is said if it was not possible to advance or finish.
`finishText`	`string`	—
`headingLevel`	`WizardHeadingLevel`	Level of the title of each step, so as not to break the page's headings. By default, 3.
`index`	`number`	—
`nextText`	`string`	—
`onError`	`(error: unknown, key: string) => void`	What is done with the error if `onExit` or `onFinish` fail, besides saying it on screen: sending it to the application's log. It receives the error and the key of the step. Without this it goes to the console, with the step and the process.
`onFinish`	`() => void \| Promise<void>`	Called when the last step finishes.
`onStepChange`	`(index: number) => void`	—
`previousText`	`string`	—
`size`	`"sm" \| "md" \| "lg"`	The gap between the steps, the content and the buttons.
`stepsLabel`	`string`	Name of the row of steps. By default, "Steps: " and the `label` as is.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-wizard-gap`	`var(--amset-space-5)`

How to change it

.amset-wizard {
  --amset-wizard-gap: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: