UX Patterns Guide
UI + UX Input And Data Entry standard

Wizard

Guide users through a bounded wizard with explicit step state, prerequisite validation, step-specific actions, generated preview or test feedback, review before finish, safe cancellation, and recomputation of dependent steps after earlier choices change.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • A setup, import, object creation, or configuration task has strict sequencing.
  • Later steps depend on earlier choices, credentials, templates, mappings, permissions, or tests.
  • Users need guided completion with a final Finish action and a safe Cancel path.
  • The product must preview, test, or review generated consequences before committing.

Avoid when

  • The task is a short form that users should scan and submit on one page.
  • The flow is primarily a public-service transaction where a multi-step form is clearer.
  • Users can complete tasks in any order and need a task list or process list.
  • The system cannot preserve wizard draft state or explain cancel behavior.
  • The step count changes heavily enough that visible progress would mislead users.

Problem it prevents

Complex setup tasks become risky when users must know the dependency order, test requirements, generated outputs, and final consequences without a guided assistant that keeps each step honest.

Pattern anatomy

What a strong implementation has to make clear

User need

The task creates or configures something with dependencies, such as an integration, report, import, automation rule, device setup, or account configuration.

Pattern promise

Guide users through a bounded wizard with explicit step state, prerequisite validation, step-specific actions, generated preview or test feedback, review before finish, safe cancellation, and recomputation of dependent steps after earlier choices change.

Required state

Not-started state that explains what the wizard will configure and how many major steps follow.

Recovery path

Finish commits an incomplete or untested setup.

Access contract

Use one clear wizard title and one current step heading; keep browser title, heading, and progress context synchronized.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A connector setup wizard shows Choose connector, Configure access, Test connection, Review, and Finish in a side step list, with Configure access current and future steps disabled until prerequisites pass.
  • The Test connection step has a primary Run test action, a result panel, and only then unlocks Review and Finish.
  • A user selects Zendesk, enters a token, runs a connection test, reviews generated sync settings, goes Back, and the token and test state are preserved or clearly invalidated when changed.
  • A user clicks Cancel halfway through setup and sees a paused draft or discard confirmation instead of losing the partial configuration.
Weak implementation

Vague, hidden, hard to recover from

  • A generic Step 1, Step 2, Done strip wraps one text field and a Finish button with no dependency, preview, review, or cancel state.
  • All steps are visible as visited while hidden required setup is inserted later, so the step count and current heading are dishonest.
  • A user clicks Finish before the connector was tested and later discovers the integration never ran.
  • A user goes Back to change the connector and the wizard silently keeps review answers from the old connector.
UI guidance
  • Render a bounded assistant shell with a clear wizard title, current step heading, step list or progress context, step-specific body content, Back, Next or step-specific primary action, Finish, and Cancel or Close.
  • Make future, hidden, optional, current, complete, error, testing, review, and finished states visible from actual setup state; do not make the step list look complete because screens were visited.
UX guidance
  • Use a wizard when users must be guided through a dependent setup, creation, import, or configuration task where each step prepares the next one and final finish should be gated.
  • Validate and save the local draft at each step, run required tests or previews before review, preserve state on Back, and provide a safe cancel path that explains whether the draft is paused, saved, or discarded.
Implementation contract

What the implementation must handle

States

  • Not-started state that explains what the wizard will configure and how many major steps follow.
  • Current guided step with a clear heading, local controls, and step-specific primary action.
  • Disabled future step state before prerequisites pass.
  • Completed step state based on saved valid setup data.

Interaction

  • Next validates and stores the current step before moving forward.
  • Step links can move only to completed or currently available steps unless the wizard explicitly supports non-linear editing.
  • Back preserves entered data and returns to the previous guided step without activating finish or rerunning side effects.
  • Step-specific actions such as Run test or Generate preview must complete before Review or Finish unlocks.

Accessibility

  • Use one clear wizard title and one current step heading; keep browser title, heading, and progress context synchronized.
  • Expose step navigation as navigation or an ordered list with current, complete, disabled, error, and stale text states.
  • Do not rely on color alone for completed, disabled, current, failed-test, or review-ready states.
  • Move focus to the step heading after Next or Back, or to the first invalid control after validation fails.

Review

  • What dependency makes this a wizard rather than an ordinary multi-step form?
  • Which step-specific action proves a step is complete?
  • Can users cancel safely without losing work unexpectedly?
  • What later steps become stale when each earlier choice changes?
Interactive lab

Inspect the states before you copy the pattern

Configure a guided setup wizard

Choose a connector, unlock the next step, test credentials, review generated settings, cancel safely, and finish only after validation passes.

Wizard
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

Not-started state that explains what the wizard will configure and how many major steps follow.

Keyboard / Access

Tab reaches the current step controls, step-specific primary action, Back, Cancel, and available step links in a predictable order.

Avoid Generating

Using wizard chrome for a short edit form with no dependent sequence.
Evidence trail

Source-backed claims behind this guidance

PatternFly Wizard component

PatternFly - checked

PatternFly documents wizard workflows with guided steps, disabled and progressive behavior, review, cancel, custom footer, save, and focus-after-navigation behavior.

Material Design Steppers

Material Design - checked

Material defines steppers as logical numbered steps with editable, optional, linear, and non-linear variants plus overuse guidance.

Full agent/debug reference

Problem Context

  • The task creates or configures something with dependencies, such as an integration, report, import, automation rule, device setup, or account configuration.
  • Later steps depend on earlier selections or credentials and may need tests, generated previews, or external validation.
  • Users need a clear path to finish or cancel without accidentally activating an incomplete setup.

Selection Rules

  • Choose a wizard when the product must guide users through a strict or mostly strict setup sequence with dependent choices.
  • Use multi-step form instead when the task is primarily collecting submitted answers across saved pages.
  • Use step navigation only as progress display inside a wizard or multi-step form, not as the wizard logic itself.
  • Use a process list when users need to understand or complete a broader process outside one controlled assistant.
  • Use a single-page form when all inputs are short, related, and safer to scan together before one save.
  • Gate Next, Review, and Finish using real prerequisites such as a valid choice, credential, import mapping, test result, or generated preview.
  • Use step-specific primary actions when they describe the real work better than Next, such as Test connection, Map columns, Generate preview, or Confirm review.
  • Provide Cancel or Close behavior that preserves, pauses, or explicitly discards setup state rather than silently losing it.
  • Retest or mark later steps stale when an earlier connector, template, permission, mapping, or option changes.

Required States

  • Not-started state that explains what the wizard will configure and how many major steps follow.
  • Current guided step with a clear heading, local controls, and step-specific primary action.
  • Disabled future step state before prerequisites pass.
  • Completed step state based on saved valid setup data.
  • Validation or test-failed state that keeps users on the owning step with recovery guidance.
  • Generated preview or test-passed state before review unlocks.
  • Review state that summarizes choices and generated consequences before finish.
  • Cancel or close state that explains draft preservation or discard.
  • Finished state only after required steps, tests, and review are complete.
  • Stale dependent step state after an earlier wizard choice changes.

Interaction Contract

  • Next validates and stores the current step before moving forward.
  • Step links can move only to completed or currently available steps unless the wizard explicitly supports non-linear editing.
  • Back preserves entered data and returns to the previous guided step without activating finish or rerunning side effects.
  • Step-specific actions such as Run test or Generate preview must complete before Review or Finish unlocks.
  • Cancel and Close never discard a partial setup without an explicit saved, paused, or discard state.
  • Changing an upstream setup choice invalidates or recomputes dependent tests, previews, review summaries, and finish eligibility.
  • Finish performs the final commit only once all required steps and review gates are satisfied.

Implementation Checklist

  • Model wizard steps with stable IDs, route or panel ownership, prerequisites, completion rules, side effects, and stale-dependency rules.
  • Write step-specific footer actions and disable or explain unavailable future steps.
  • Persist draft state before navigation and restore it on Back, close, refresh, validation errors, and return from review.
  • Separate local step validation from final Finish side effects.
  • Provide test, preview, or generated-output states for steps that create external consequences.
  • Add a review step for irreversible, high-cost, external, or generated setup changes.
  • Confirm cancel or clearly communicate whether the wizard draft is saved, paused, or discarded.
  • Move focus to the new step heading or first invalid control after navigation and validation.
  • Test keyboard navigation through step list, footer actions, disabled steps, cancel, review change links, and final finish.

Common Generated-UI Mistakes

  • Using wizard chrome for a short edit form with no dependent sequence.
  • Letting users finish before required tests, previews, or review pass.
  • Treating step navigation as the whole wizard while leaving draft state and finish behavior undefined.
  • Hiding conditional steps until after users relied on the displayed count.
  • Using generic Next on steps whose actual obligation is Test, Map, Preview, or Confirm.
  • Discarding partial setup on Cancel without a warning or draft recovery.
  • Keeping stale generated settings after an earlier connector or template changes.

Critique Questions

  • What dependency makes this a wizard rather than an ordinary multi-step form?
  • Which step-specific action proves a step is complete?
  • Can users cancel safely without losing work unexpectedly?
  • What later steps become stale when each earlier choice changes?
  • Is Finish impossible until every required test, preview, and review gate has passed?
  • Would a process list or task list be more honest because users can work out of order?
Accessibility
  • Use one clear wizard title and one current step heading; keep browser title, heading, and progress context synchronized.
  • Expose step navigation as navigation or an ordered list with current, complete, disabled, error, and stale text states.
  • Do not rely on color alone for completed, disabled, current, failed-test, or review-ready states.
  • Move focus to the step heading after Next or Back, or to the first invalid control after validation fails.
  • Make Cancel, Back, step-specific primary action, Review, and Finish reachable in predictable keyboard order.
  • If step navigation is interactive, keep disabled future steps unfocusable or announce why they are unavailable.
  • Ensure icon-only progress segments have accessible names or hide decorative connectors from assistive technology.
Keyboard Behavior
  • Tab reaches the current step controls, step-specific primary action, Back, Cancel, and available step links in a predictable order.
  • Enter or Space activates available step navigation and footer buttons.
  • After Next or Back, focus moves to the new step heading or the first validation error.
  • Disabled future steps do not trap focus and expose unavailable status where they remain visible.
  • Escape may close a modal wizard only if it follows the same cancel confirmation or draft-preservation rule as Cancel.
  • Finish is not reachable as an enabled action until required steps, tests, previews, and review are complete.
Variants
  • Linear setup wizard
  • Progressive wizard
  • Modal wizard
  • Full-page wizard
  • Configuration wizard
  • Import wizard
  • Onboarding wizard
  • Creation wizard with generated preview
  • Wizard with required test step
  • Wizard with review before finish

Verification

Last verified: