Wizard

A wizard is a guided form that splits one job into steps or short questions, so a user does not face every option at once. Drupal does not have one wizard system. The word names a pattern that core, contributed modules and custom code each build in their own way.

How wizards work in Drupal 11

In the core administrative interface, the wizard is the Views add form at /admin/structure/views/add, handled by ViewAddForm as a single form rather than a series of pages. A Show dropdown lists the available wizard plugins, and changing it rebuilds the rest of the form by AJAX for that choice. Wizards are plugins that implement WizardInterface; the wizards in core extend WizardPluginBase. On submit the selected plugin's createView() builds the view.

Developers who need several steps can take one of two routes:

• Rebuild the form. FormStateInterface::setRebuild() tells Drupal to build the form again after processing. The Examples for Developers module uses it for a two-step form: a page_num value in the form state selects which step buildForm() returns, and the first step's values are stored there too.
• Use CTools. The Chaos Tool Suite module provides FormWizardBase and FormWizardInterface. A wizard class lists its steps in getOperations(), each with a title and the class of that step's form, and keeps the values between steps in a tempstore. Version 4.1.1 supports Drupal 9.5, 10 and 11, according to its project page.

The wizard classes above are built on the Form API. Contributed modules use the pattern too; the Webform project page lists multi-step forms among its features.

Example

This sketch shows the shape of a CTools wizard. A real class also needs a machine name and a route; see the interface.

public function getOperations($cached_values) {
          return [
            'basics' => [
              'title' => $this->t('Basics'),
              'form' => BasicsForm::class,
            ],
            'review' => [
              'title' => $this->t('Review'),
              'form' => ReviewForm::class,
            ],
          ];
        }
        

Common mistakes

• Forgetting the rebuild. If buildForm() branches on a step number, the submit handler must call setRebuild(TRUE). Without it the user keeps seeing the old step.
• Expecting CTools on every site. It is a contributed module. Add it with Composer before a custom wizard depends on it.

For marketing and content teams

You will meet the wizard when you ask for a new listing: the Views add form is where a new view starts. For a long form on the site, ask whether a multi-step layout would help, since Webform supports multi-step forms. Test every step on a phone before it goes live.

Sources

• Drupal core 11.4.10: ViewAddForm.php (Views UI)
• Drupal core 11.4.10: WizardPluginBase.php (Views)
• Drupal core 11.4.10: DefaultWizardDeriver.php (Views)
• Drupal core 11.4.10: FormStateInterface.php
• Examples for Developers 4.0.x: MultistepForm.php
• Chaos Tool Suite (CTools) 4.1.1: FormWizardInterface.php
• Drupal.org: Chaos Tool Suite project page (checked 2026-10-26)
• Drupal.org: Webform project page (checked 2026-10-26)