Wizard

Split a form’s input across multiple pages with Back / Next navigation.

What is a wizard?

A wizard turns a single form into a sequence of pages. Each page is rendered from a subform and the user navigates with Back and Next buttons. Validation is gated per page — you cannot move forward until the current step is valid (unless the step is marked optional).

A read-only review page is appended automatically at the end of every wizard. It lists each step and its collected values so the user can confirm before submitting. You do not declare it in YAML — its title is taken from the active locale.

When the user submits, the collected values from all steps are merged into a single extravars payload and sent to the underlying playbook / template / multistep — exactly as if the user had filled in one big form.

Wondering how wizard differs from a multistep form, or how the two combine? See the FAQ entry What is the difference between a wizard and a multistep form?.

Form-level property

Attribute

Comments

wizard array added in version 6.4.0

Wizard steps (form-layer) Turn a form into a multi-page wizard. Where steps splits the execution into multiple jobs, wizard splits the input of a single form into multiple pages. Each wizard step references a subform and is rendered as its own page with Back / Next navigation. A read-only review page is appended automatically as the last step — you do not declare it in YAML. See the Wizard page for all step properties and examples.

Examples:

1) Three-step wizard

name: Provision host
type: ansible
playbook: provision.yml
wizard:
  - subform: basics
    title: Basics
  - subform: network
    title: Network
    defaultModel: net
  - subform: advanced
    title: Advanced
    optional: true
    when: $(__parent__.basics.kind) === 'vm'

2) Wizard mapped one-to-one onto multistep (defaultModel + key)

name: Provision and verify host
type: multistep
wizard:
  - subform: basics
    title: Basics
    defaultModel: basics      # wraps fields under `basics`
  - subform: network
    title: Network
    defaultModel: network     # wraps fields under `network`
steps:
  - name: Create host
    type: ansible
    playbook: create_host.yml
    key: basics                # receives only the basics payload
  - name: Configure network
    type: ansible
    playbook: configure_network.yml
    key: network                # receives only the network payload

Wizard step properties

Each wizard step references a subform and is rendered as its own page with Back and Next navigation. The user must validate one step before moving to the next; data from earlier steps is available in later steps via __parent__.

Review step is automatic. A read-only summary page that lists every step’s input is appended as the last page of the wizard. You do not declare it in YAML — its title is taken from the active locale (“Summary” / “Samenvatting” / “Zusammenfassung” / …).

Wizard vs Multistep. steps splits the execution into multiple sequential jobs (each step is its own playbook/template). wizard splits the input of a single form into multiple pages — only one job runs at the end. The two can be combined: a type: multistep form can also have a wizard: block to gather its extravars across pages.

Attribute	Comments
basic
subform string / required	Subform reference a valid subform name The name of a type: subform form to render on this wizard page. The subform’s fields become this step’s inputs. Examples: 1) Reference a subform wizard: - subform: basics - subform: network
name string	Step namespace key alphanumeric + dash + underscore The key under which this step’s values are exposed to later steps via $(__parent__.<name>.<field>). Defaults to the value of subform when omitted. Set this explicitly when you reuse the same subform multiple times in the same wizard, or when you want a stable key independent of the subform name. Examples: 1) Override the namespace wizard: - subform: address name: shipping - subform: address name: billing
title string	Page title in the stepper free text Title shown in the wizard stepper and at the top of the page. Defaults to the subform’s description, or to the step’s name if no description is set. Examples: 1) Custom title wizard: - subform: basics title: Tell us about your host
help string	Help text shown on this page free text (markdown supported) Help text rendered on the wizard page. Defaults to the subform’s own help when omitted.
showHelp boolean	Show help on load true, false When true, the help block is expanded by default when the user lands on this page. Falls back to the subform’s showHelp when omitted. Default: false
defaultModel string	Wrap this step's output under a prefix a model path (dot notation allowed) Wraps every field of this step under the given object key in the final extravars payload. Useful when you reuse a generic subform and want its values namespaced. Without defaultModel, fields are merged into the top level of the extravars (still grouped per step under __parent__ for cross-step references). Examples: 1) Wrap network fields under `net` wizard: - subform: network defaultModel: net # The subform has fields `hostname` and `ipv4`. # Final extravars contain: # net: # hostname: ... # ipv4: ...
workflow
when expression	Conditionally show this step a JavaScript expression returning truthy/falsy When the expression evaluates falsy, the step is hidden entirely — the user never sees it and its values are not collected. The expression has access to all earlier steps via __parent__.<stepname>.<field>. Steps after a hidden one are renumbered automatically. Note: when is purely about visibility; it is unrelated to optional, which is about whether the user is allowed to skip a visible step. Examples: 1) Only show when kind is "vm" wizard: - subform: basics # has a `kind` enum field - subform: advanced when: $(__parent__.basics.kind) === 'vm'
optional boolean	Allow skipping this step true, false When true, the user can press Next even if the step’s fields are not (yet) valid, and Submit is allowed without ever visiting this step. The step is still shown in the stepper — use when if you want to hide it altogether. Default: false Examples: 1) Optional advanced page wizard: - subform: basics - subform: advanced optional: true
Examples
1) Minimal wizard (review page is auto-added) - name: Provision host type: ansible playbook: provision.yml wizard: - subform: basics - subform: network - name: basics type: subform fields: - name: hostname type: text required: true - name: network type: subform fields: - name: ipv4 type: text 2) Cross-step reference and namespace prefix wizard: - subform: basics title: Basics - subform: network title: Network defaultModel: net # wraps network fields under `net` # In the `network` subform you can reference fields # from the `basics` step like this: # default: $(__parent__.basics.hostname).local

---

Combining a wizard with multistep

A wizard can be layered on top of a multistep form. Pair each wizard step’s defaultModel with the matching multistep step’s key and each playbook/template will receive only the values from its own wizard page.

See the FAQ for a worked example and the merged-extravars layout: What is the difference between a wizard and a multistep form? (section Combined — wizard on top of multistep).

See also

• Subform — wizard pages are rendered from subforms
• Multistep forms — the execution-layer counterpart of wizard
• __parent__ in subforms — how to reference earlier wizard steps from a later step