Navigation
Wizard
A form split into steps, with a progress trail, Back and Continue buttons, and a check on each step before moving on.
Use a wizard when a long form reads better in parts, such as a quote or an onboarding flow. Each step is checked before the next opens, so mistakes are caught where they were made. For a progress trail without the form around it, use Stepper.
Preview
Section titled “Preview”Check the details, then finish to request a quote.
<nana-wizard label="Motor cover" style="width: 100%; max-width: 36rem">
<nana-wizard-step label="Owner" description="Who holds the policy">
<nana-input label="Full name" required></nana-input>
<nana-input label="ID number" required></nana-input>
</nana-wizard-step>
<nana-wizard-step label="Vehicle" description="What is covered">
<nana-input label="Registration" required></nana-input>
<nana-input label="Year of manufacture" type="number"></nana-input>
</nana-wizard-step>
<nana-wizard-step label="Review">
<p>Check the details, then finish to request a quote.</p>
</nana-wizard-step>
</nana-wizard> Step 1 of 3: Owner
<script lang="ts">
import { NanaInput, NanaWizard } from '$lib';
const steps = [
{ label: 'Owner', description: 'Who holds the policy' },
{ label: 'Vehicle', description: 'What is covered' },
{ label: 'Review' },
];
let finished = $state(false);
</script>
<div class="w-full max-w-xl">
{#if finished}
<p role="status">Quote requested. We will send it by SMS.</p>
{:else}
<NanaWizard {steps} label="Motor cover" onFinish={() => (finished = true)}>
{#snippet children({ index })}
{#if index === 0}
<NanaInput label="Full name" name="name" required />
<NanaInput label="ID number" name="id" required />
{:else if index === 1}
<NanaInput label="Registration" name="plate" required />
<NanaInput label="Year of manufacture" name="year" type="number" />
{:else}
<p>Check the details, then finish to request a quote.</p>
{/if}
{/snippet}
</NanaWizard>
{/if}
</div> Installation
Section titled “Installation”Install the package for a versioned dependency:
npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add wizard --framework web-componentsnpx @nana-tec/ui add wizard --framework svelteLands in src/lib/components/ui/wizard/ as NanaWizard.svelte, together with
the stepper and button it uses, styled with Tailwind classes that resolve to the
design tokens. Requires Tailwind v4.
Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and
each component downloads only the first time a page uses it:
import "@nana-tec/ui-components/autoloader";import "@nana-tec/ui-components/theme";The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.
Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:
import "@nana-tec/ui-components/wizard";
Copied in with npx @nana-tec/ui add wizard? Import your project's own
@/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.
Each nana-wizard-step holds one step’s fields. Its label names the step in
the trail and to screen readers; description adds a line under it.
<nana-wizard label="Motor cover"> <nana-wizard-step label="Owner">…</nana-wizard-step> <nana-wizard-step label="Vehicle">…</nana-wizard-step> <nana-wizard-step label="Review">…</nana-wizard-step></nana-wizard>
<script type="module"> const wizard = document.querySelector('nana-wizard'); wizard.addEventListener('nana-wizard-finish', () => submitQuote());</script>Pass the steps as data and render each one from the children snippet, which
receives the step’s index and the step itself.
<script lang="ts"> import { NanaWizard } from '$lib/components/ui/wizard';
const steps = [{ label: 'Owner' }, { label: 'Vehicle' }, { label: 'Review' }];</script>
<NanaWizard {steps} label="Motor cover" onFinish={submitQuote}> {#snippet children({ index })} {#if index === 0} <!-- owner fields --> {:else if index === 1} <!-- vehicle fields --> {:else} <!-- summary --> {/if} {/snippet}</NanaWizard>current and completed are bindable, so a page can restore a half-finished
flow. onStepChange reports every move.
Checking a step
Section titled “Checking a step”Continue first checks every field in the step, native or Nana, the same way a form would. The first invalid field shows its message and takes focus, and the wizard stays where it is.
For a rule the fields cannot express, such as a lookup on the server, give the
wizard validate. It receives the step’s index and returns true to move on,
or a promise of it. Continue shows a spinner while the promise is pending.
wizard.validate = async (index) => { if (index !== 1) return true; return await registrationExists(plate.value);};<NanaWizard {steps} validate={async (index) => index !== 1 || (await registrationExists(plate))}>Button text
Section titled “Button text”The buttons read Back, Continue and Finish. Change them for another language or a clearer action:
<nana-wizard back-label="Nyuma" next-label="Endelea" finish-label="Tuma ombi">…</nana-wizard><NanaWizard {steps} labels={{ back: 'Nyuma', next: 'Endelea', finish: 'Tuma ombi' }}>Accessibility
Section titled “Accessibility”- The step on show is a group named after the step. Moving to another step focuses it, so a keyboard or screen reader user starts at the top of the new fields.
- A polite status announces each move, for example “Step 2 of 3: Vehicle”.
- The progress trail is a labelled list of steps; completed steps can be revisited from it, later ones only through Continue.
- Back is disabled on the first step rather than hidden, so the buttons do not move.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
backLabel | back-label | — | — | Text of the Back button. |
completed | completed | number[] | [] | Indices of the steps already finished. |
current | current | number | 0 | Zero-based index of the step on show. |
finishLabel | finish-label | — | — | Text of the forward button on the last step. |
label | label | string | 'Progress' | Accessible name of the progress trail. |
nextLabel | next-label | — | — | Text of the forward button before the last step. |
validate | — | (index: number) => boolean | Promise<boolean> | undefined | — | Called with the step index before moving on; return false, or a promise of false, to stay. |
Methods
| Method | Description |
|---|---|
next(): Promise<void> | Check the current step and move on, or finish on the last step. |
previous(): void | Go back one step. |
Events
| Event | Description |
|---|---|
nana-step-change | After the wizard moves to another step; detail: { current: number, previous: number } |
nana-wizard-finish | When Finish is pressed on a valid last step |
Slots
| Slot | Description |
|---|---|
(default) | The nana-wizard-step children, in order |
CSS parts
| Part | Description |
|---|---|
::part(base) | The wizard container |
::part(stepper) | The progress trail |
::part(actions) | The row holding the buttons |
::part(back) | The Back button |
::part(forward) | The Continue or Finish button |
CSS custom properties
| Property | Description |
|---|---|
--nana-wizard-gap | Space between the trail, the step and the buttons |
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
active | active | boolean | false | Set by the wizard on the step it is showing. |
description | description | string | '' | A short line under the label in the progress trail. |
label | label | string | '' | The step's name, shown in the progress trail and announced on arrival. |
Slots
| Slot | Description |
|---|---|
(default) | The step's content, usually its fields |
NanaWizard
| Prop | Type | Default |
|---|---|---|
stepsrequired | readonly WizardStep[] | |
currentbind: | number | 0 |
completedbind: | number[] | [] |
label | string | 'Progress' |
labels | Partial<WizardLabels> | {} |
validate | (index: number) => boolean | Promise<boolean> | |
onStepChange | (index: number) => void | |
onFinish | () => void | Promise<void> | |
childrenrequired | Snippet<[{ index: number; step: WizardStep }]> |
Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'>.
steps, each with a label and an optional description, and the children
snippet are required. label names the progress trail. labels replaces the
button text. validate, onStepChange and onFinish are described above.