Wizards

You are currently viewing the documentation for Filament 4.x, which is a previous version of Filament.Looking for the current stable version? Visit the 5.x documentation.

Introduction

Similar to tabs, you may want to use a multistep wizard to reduce the number of components that are visible at once. These are especially useful if your form has a definite chronological order, in which you want each step to be validated as the user progresses.

use Filament\Schemas\Components\Wizard;
use Filament\Schemas\Components\Wizard\Step;

Wizard::make([
    Step::make('Order')
        ->schema([
            // ...
        ]),
    Step::make('Delivery')
        ->schema([
            // ...
        ]),
    Step::make('Billing')
        ->schema([
            // ...
        ]),
])

We have different setup instructions if you’re looking to add a wizard to the creation process inside a panel resource or an action modal. Following that documentation will ensure that the ability to submit the form is only available on the last step of the wizard.

Rendering a submit button on the last step

You may use the submitAction() method to render submit button HTML or a view at the end of the wizard, on the last step. This provides a clearer UX than displaying a submit button below the wizard at all times:

use Filament\Schemas\Components\Wizard;
use Illuminate\Support\HtmlString;

Wizard::make([
    // ...
])->submitAction(view('order-form.submit-button'))

Wizard::make([
    // ...
])->submitAction(new HtmlString('<button type="submit">Submit</button>'))

Alternatively, you can use the built-in Filament button Blade component:

use Filament\Schemas\Components\Wizard;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\HtmlString;

Wizard::make([
    // ...
])->submitAction(new HtmlString(Blade::render(<<<BLADE
    <x-filament::button
        type="submit"
        size="sm"
    >
        Submit
    </x-filament::button>
BLADE)))

You could extract this component to a separate Blade view if you prefer.

Setting a step icon

Steps may have an icon, which you can set using the icon() method:

use Filament\Schemas\Components\Wizard\Step;
use Filament\Support\Icons\Heroicon;

Step::make('Order')
    ->icon(Heroicon::ShoppingBag)
    ->schema([
        // ...
    ]),

Customizing the icon for completed steps

You may customize the icon of a completed step using the completedIcon() method:

use Filament\Schemas\Components\Wizard\Step;
use Filament\Support\Icons\Heroicon;

Step::make('Order')
    ->completedIcon(Heroicon::HandThumbUp)
    ->schema([
        // ...
    ]),

Adding descriptions to steps

You may add a short description after the title of each step using the description() method:

use Filament\Schemas\Components\Wizard\Step;

Step::make('Order')
    ->description('Review your basket')
    ->schema([
        // ...
    ]),

Setting the default active step

You may use the startOnStep() method to load a specific step in the wizard:

use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])->startOnStep(2)

Allowing steps to be skipped

If you’d like to allow free navigation, so all steps are skippable, use the skippable() method:

use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])->skippable()

Optionally, the skippable() method accepts a boolean value to control if the steps are skippable or not:

use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])->skippable(FeatureFlag::active())

Deferring the loading of step content

If the content of a wizard step is expensive to render, you can pass a Schema object to its schema() method and use deferLoading(). The content of the active step will be loaded when it enters the viewport. The content of a later step will not be loaded until the user reaches it:

use Filament\Forms\Components\TextInput;
use Filament\Schemas\Components\Wizard;
use Filament\Schemas\Components\Wizard\Step;
use Filament\Schemas\Schema;

Wizard::make([
    Step::make('Account')
        ->key('accountStep')
        ->schema(
            Schema::make()
                ->components([
                    TextInput::make('name'),
                ])
                ->deferLoading(),
        ),
    Step::make('Confirmation')
        ->key('confirmationStep')
        ->schema(
            Schema::make()
                ->components([
                    // ...
                ])
                ->deferLoading(),
        ),
])
    ->key('accountWizard')

Every deferred schema must have a unique key. In this example, the keys on the steps are inherited by their child schemas, while the key on the Wizard component namespaces them from other steps in the same schema. You can learn more in the schema overview.

Persisting the current step in the URL’s query string

By default, the current step is not persisted in the URL’s query string. You can change this behavior using the persistStepInQueryString() method:

use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])->persistStepInQueryString()

When enabled, the current step is persisted in the URL’s query string using the step key. You can change this key by passing it to the persistStepInQueryString() method:

use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])->persistStepInQueryString('wizard-step')

Step lifecycle hooks

You may use the afterValidation() and beforeValidation() methods to run code before and after validation occurs on the step:

use Filament\Schemas\Components\Wizard\Step;

Step::make('Order')
    ->afterValidation(function () {
        // ...
    })
    ->beforeValidation(function () {
        // ...
    })
    ->schema([
        // ...
    ]),

Preventing the next step from being loaded

Inside afterValidation() or beforeValidation(), you may throw Filament\Support\Exceptions\Halt, which will prevent the wizard from loading the next step:

use Filament\Schemas\Components\Wizard\Step;
use Filament\Support\Exceptions\Halt;

Step::make('Order')
    ->afterValidation(function () {
        // ...

        if (true) {
            throw new Halt();
        }
    })
    ->schema([
        // ...
    ]),

Using grid columns within a step

You may use the columns() method to customize the grid within the step:

use Filament\Schemas\Components\Wizard;
use Filament\Schemas\Components\Wizard\Step;

Wizard::make([
    Step::make('Order')
        ->columns(2)
        ->schema([
            // ...
        ]),
    // ...
])

Customizing the wizard action objects

This component uses action objects for easy customization of buttons within it. You can customize these buttons by passing a function to an action registration method. The function has access to the $action object, which you can use to customize it. The following methods are available to customize the actions:

nextAction()
previousAction()

Here is an example of how you might customize an action:

use Filament\Actions\Action;
use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])
    ->nextAction(
        fn (Action $action) => $action->label('Next step'),
    )

Introduction

Guides

Resources

Tables

Schemas

Forms

Infolists

Actions

Notifications

Widgets

Configuration

Navigation

Users

Styling

Advanced

Testing

Plugins

Components

Deployment

Upgrading

Introduction

Rendering a submit button on the last step

Setting a step icon

Customizing the icon for completed steps

Adding descriptions to steps

Setting the default active step

Allowing steps to be skipped

Deferring the loading of step content

Persisting the current step in the URL’s query string

Step lifecycle hooks

Preventing the next step from being loaded

Using grid columns within a step

Customizing the wizard action objects

​Introduction

​Rendering a submit button on the last step

​Setting a step icon

​Customizing the icon for completed steps

​Adding descriptions to steps

​Setting the default active step

​Allowing steps to be skipped

​Deferring the loading of step content

​Persisting the current step in the URL’s query string

​Step lifecycle hooks

​Preventing the next step from being loaded

​Using grid columns within a step

​Customizing the wizard action objects

Introduction

Rendering a submit button on the last step

Setting a step icon

Customizing the icon for completed steps

Adding descriptions to steps

Setting the default active step

Allowing steps to be skipped

Deferring the loading of step content

Persisting the current step in the URL’s query string

Step lifecycle hooks

Preventing the next step from being loaded

Using grid columns within a step

Customizing the wizard action objects