Wizard (Multi-Step Forms)

Introduction

Wizard mode turns a form into a multi-step flow. Each fieldset becomes a step, with navigation controls, a connected progress indicator, and optional per-step validation. This is useful for long forms where showing all fields at once would overwhelm the user.

PHP Setup

Enable wizard mode on a form by defining a wizard() method that returns a WizardConfig. Each fieldset in your fields() method becomes one step. Without explicit steps, the fieldset legend and description are used. Once a step is configured, its title, description, and icon are treated as the step copy.

Example

php

use InertiaUI\Forms\Fields\Fieldset;
use InertiaUI\Forms\Fields\TextInput;
use InertiaUI\Forms\Fields\Combobox;
use InertiaUI\Forms\Fields\Textarea;
use InertiaUI\Forms\Form;
use InertiaUI\Forms\WizardConfig;

class OnboardingForm extends Form
{
    protected ?string $actionRoute = 'onboarding.store';

    public function fields(): array
    {
        return [
            Fieldset::make([
                TextInput::make('name')->required(),
                TextInput::make('email')->email()->required(),
            ])->legend('Account'),

            Fieldset::make([
                Combobox::make('role')->options([...]),
                TextInput::make('company'),
            ])->legend('Profile'),

            Fieldset::make([
                Textarea::make('bio'),
            ])->legend('About You'),
        ];
    }

    public function wizard(): WizardConfig
    {
        return WizardConfig::make()
            ->step('Account', 'Create your login', 'UserIcon')
            ->step('Profile', 'Tell us about your work', 'BriefcaseIcon')
            ->step('About You')
            ->validateOnStep()
            ->labels(next: 'Continue', prev: 'Back', submit: 'Finish');
    }
}

Wizard Configuration

The wizard behavior is controlled through the WizardConfig passed from PHP. You may pass steps to make([...]), replace them with steps([...]), append them with step(...).

php

use InertiaUI\Forms\WizardConfig;

public function wizard(): WizardConfig
{
    return WizardConfig::make()
        ->allowSkip()
        ->showProgress()
        ->showStepNumbers()
        ->showStepTitles()
        ->showStepDescriptions()
        ->progressLayout('vertical')
        ->progressVariant('timeline')
        ->validateOnStep()
        ->nextLabel('Continue')
        ->prevLabel('Back')
        ->submitLabel('Finish');
}

Most wizard options are booleans:

Option	Default	Description
`enabled`	`true`	Limits wizard rendering to the first visible fieldset when disabled. Render `Form` for the complete non-wizard layout.
`allowSkip`	`false`	Allow skipping ahead to unvisited steps
`showProgress`	`true`	Show or hide the complete progress bar and step-navigation list.
`showStepNumbers`	`true`	Show numbers when a step has no configured icon. Completed and error states use status icons.
`showStepTitles`	`true`	Show step titles in the progress navigation. Set this to `false` for a checks-only stepper.
`showStepDescriptions`	`true`	Show step descriptions in progress variants that have room for subtitle copy.
`validateOnStep`	`false`	Validate current step fields before advancing

Layout, step, and label options carry explicit values:

Option	Type	Default	Description
`steps`	`WizardStep[]`	`[]`	Explicit step titles, descriptions, and icons. Entries map to original fieldset positions. Missing step entries fall back to fieldset copy.
`progressLayout`	`'horizontal' \| 'vertical'`	`'horizontal'`	Choose whether the built-in progress navigation is arranged horizontally or vertically.
`progressVariant`	`'default' \| 'compact' \| 'timeline' \| 'bar'`	`'default'`	Choose the built-in visual style for the progress navigation.
`nextLabel`	`string \| null`	`null`	Next button label. `null` uses the translated `wizard_next` value.
`prevLabel`	`string \| null`	`null`	Back button label. `null` uses the translated `wizard_prev` value.
`submitLabel`	`string \| null`	`null`	Last-step submit label. `null` uses the translated `wizard_submit` value.

There are two distinct kinds of labels, so keep them straight:

Step titles name each step in the progress indicator. Set them with step('Account', 'Create your login'), or pass an optional third icon string with step('Account', 'Create your login', 'UserIcon'). Without configured steps, titles and descriptions fall back to the fieldset legend and description.
Navigation button labels are the Back / Next / Submit button texts. Set all three at once with labels(next: 'Continue', prev: 'Back', submit: 'Finish'), or set them individually with nextLabel(), prevLabel(), and submitLabel(). labels() is just shorthand for the three individual methods.

Each WizardStep property is optional and serializes as string | null:

Property	Description
`title`	Displayed below the step indicator. A missing title falls back to the fieldset legend, then the translated `wizard_step` label.
`description`	Smaller text below the title. Omit it on a configured step when that step should not show a subtitle.
`icon`	Icon name resolved by the built-in presenter or a custom wizard UI.

Progress Presentation

The default presenter includes several built-in progress styles:

Example

php

public function wizard(): WizardConfig
{
    return WizardConfig::make()
        ->timelineProgress()
        ->step('Plan', 'Choose the workspace defaults')
        ->step('Team')
        ->step('Confirm', 'Review and submit');
}

The horizontal layout is the default and renders a connected row of step buttons. The vertical layout stacks the same step states in a connected list. You may set progressLayout() and progressVariant() directly, or use verticalProgress(), timelineProgress(), compactProgress(), and barProgress() shortcuts. The timeline variant uses the vertical layout and keeps a dedicated variant hook for projects that want to style timeline-flavored wizards differently. The compact variant uses small step chips and hides description copy, which is useful when the form content should dominate. The bar variant renders a linear progress bar with step labels underneath.

Descriptions are optional. A configured step without a description does not reserve empty subtitle space. You may call showStepDescriptions(false) for a tighter presenter when descriptions are configured.

Numbers are optional too. Call showStepNumbers(false) to use status markers without numeric labels. The current step renders a dot, completed steps render a check, and pending steps stay empty. For a checks-only progress control, combine showStepNumbers(false) with showStepTitles(false).

Step Visibility

Wizard fieldsets use Conditional Visibility. Hidden fieldsets are omitted from browser step navigation, and configured step labels still map to their original fieldset positions. Server-side validation uses the same fieldset visibility rules and excludes hidden fieldset children.

Step Validation

Enabling validateOnStep makes Next trigger precognitive validation on all fields in the current step. Navigation is blocked until current-step errors are resolved.

php

public function wizard(): WizardConfig
{
    return WizardConfig::make()
        ->validateOnStep();
}

This requires the relevant fields to have ->precognitive() enabled so server-side validation may run without a full form submission.

Wizard (Multi-Step Forms) ​

Introduction ​

PHP Setup ​

Wizard Configuration ​

Progress Presentation ​

Step Visibility ​

Step Validation ​