Skip to content
Nana UI

Navigation

Wizard

A form split into steps, with a progress trail, Back and Continue buttons, and a check on each step before moving on.

View .md Download

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.

Check the details, then finish to request a quote.

Step 1 of 3: Owner

Install the package for a versioned dependency:

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add wizard --framework web-components
npx @nana-tec/ui add wizard --framework svelte

Lands 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.

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))}
>

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' }}>
  • 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

PropertyAttributeTypeDefaultDescription
backLabelback-label——Text of the Back button.
completedcompletednumber[][]Indices of the steps already finished.
currentcurrentnumber0Zero-based index of the step on show.
finishLabelfinish-label——Text of the forward button on the last step.
labellabelstring'Progress'Accessible name of the progress trail.
nextLabelnext-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

MethodDescription
next(): Promise<void>Check the current step and move on, or finish on the last step.
previous(): voidGo back one step.

Events

EventDescription
nana-step-changeAfter the wizard moves to another step; detail: { current: number, previous: number }
nana-wizard-finishWhen Finish is pressed on a valid last step

Slots

SlotDescription
(default)The nana-wizard-step children, in order

CSS parts

PartDescription
::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

PropertyDescription
--nana-wizard-gapSpace between the trail, the step and the buttons

Properties

PropertyAttributeTypeDefaultDescription
activeactivebooleanfalseSet by the wizard on the step it is showing.
descriptiondescriptionstring''A short line under the label in the progress trail.
labellabelstring''The step's name, shown in the progress trail and announced on arrival.

Slots

SlotDescription
(default)The step's content, usually its fields

NanaWizard

PropTypeDefault
stepsrequiredreadonly WizardStep[]
currentbind:number0
completedbind:number[][]
labelstring'Progress'
labelsPartial<WizardLabels>{}
validate(index: number) => boolean | Promise<boolean>
onStepChange(index: number) => void
onFinish() => void | Promise<void>
childrenrequiredSnippet<[{ 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.