Wizard Component

Relevant source files

• components/src/main/java/org/patternfly/component/emptystate/EmptyState.java
• components/src/main/java/org/patternfly/component/modal/Modal.java
• components/src/main/java/org/patternfly/component/wizard/Wizard.java
• components/src/main/java/org/patternfly/component/wizard/WizardFooter.java
• components/src/main/java/org/patternfly/component/wizard/WizardFooterButtons.java
• components/src/main/java/org/patternfly/component/wizard/WizardHeaderDescription.java
• components/src/main/java/org/patternfly/component/wizard/WizardNavItem.java
• components/src/main/java/org/patternfly/component/wizard/WizardStep.java
• components/src/main/java/org/patternfly/component/wizard/WizardStepChangeHandler.java
• showcase/src/main/java/org/patternfly/showcase/SnippetPage.java
• showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java

The Wizard component provides a guided multi-step workflow for completing tasks or creating objects through a series of sequential steps. This document covers the Wizard class and its sub-components (WizardStep, WizardNav, WizardFooter, WizardHeader), navigation patterns (progressive, visit-required), step lifecycle handlers, validation mechanisms, and modal integration.

For information about Form components used within wizard steps, see 5.1. For Modal components that can contain wizards, see 5.4.

---

Architecture Overview

The Wizard component follows a composite pattern where Wizard acts as the main container managing a linked list of WizardStep items. Each step can contain arbitrary content and define handlers to control navigation flow.

Sources: components/src/main/java/org/patternfly/component/wizard/Wizard.java64-114 components/src/main/java/org/patternfly/component/wizard/WizardStep.java46-94 components/src/main/java/org/patternfly/component/wizard/WizardFooter.java35-70

---

Component Structure

Wizard Class

The Wizard class extends BaseComponent<HTMLElement, Wizard> and implements HasItems<HTMLElement, Wizard, WizardStep> to manage step collections.

Key Fields:

• Map<String, WizardStep> items - All steps indexed by identifier
• WizardStep head, current, tail - Linked list pointers
• WizardNav nav - Navigation sidebar
• WizardFooter footer - Button container
• WizardContext context - Shared data storage
• boolean progressive - Progressive step visibility mode
• boolean visitRequired - Disables unvisited steps

Primary Methods:

Method	Description
addItem(WizardStep)	Adds a step to the wizard, updates linked list and nav
select(String|WizardStep)	Navigates to a specific step
next()	Navigates to next enabled step
previous()	Navigates to previous enabled step
cancel()	Fires cancel handlers
currentStep()	Returns current active step
context()	Returns shared context for data storage

Sources: components/src/main/java/org/patternfly/component/wizard/Wizard.java64-508

WizardStep Class

The WizardStep class represents an individual step in the wizard workflow. It implements HasIdentifier, Disabled, ComponentContext, and ElementContainerDelegate.

Key Fields:

• String identifier - Unique step identifier
• String title - Display title
• WizardStepType type - Step type (step, review, progress, summary)
• HTMLElement bodyElement - Container for step content
• WizardStep previous, next - Linked list pointers
• boolean disabled, visited - State flags
• ValidationStatus status - Success, warning, or error indicator

Handler Fields:

• WizardStepNextHandler nextHandler / WizardStepNextPromise nextPromise
• WizardStepPreviousHandler previousHandler / WizardStepPreviousPromise previousPromise
• WizardStepEnterHandler enterHandler
• WizardStepLeaveHandler leaveHandler

Sources: components/src/main/java/org/patternfly/component/wizard/WizardStep.java46-296

WizardNav and WizardNavItem

The WizardNav contains a list of WizardNavItem instances that represent clickable step links in the sidebar.

WizardNavItem includes:

• Unique identifier matching WizardStep.identifier
• Display text
• Disabled state
• Optional status icon (success, warning, error)
• Click handler that calls Wizard.select(identifier)

Sources: components/src/main/java/org/patternfly/component/wizard/WizardNavItem.java52-181

WizardFooter

The WizardFooter contains three buttons managed by the wizard:

Button	Variable	Default Text	Behavior
Back	backButton	"Back"	Calls Wizard.previous()
Next	nextButton	"Next" / "Finish"	Calls Wizard.next()
Cancel	cancelButton	"Cancel"	Calls Wizard.cancel()

The footer automatically updates button states and labels based on current step position and type.

Sources: components/src/main/java/org/patternfly/component/wizard/WizardFooter.java35-127

WizardHeader

Optional header component containing:

• WizardHeaderTitle - Title text/element
• WizardHeaderDescription - Description paragraph

Sources: components/src/main/java/org/patternfly/component/wizard/WizardHeaderDescription.java27-54

WizardContext

The WizardContext provides a shared data store accessible from all steps. Each step also has its own ComponentContext for step-local data.

Usage Pattern:

// Store data in step's onLeave handler
step.onLeave((wzd, step) -> wzd.context().store("age", ageInput.value()));

// Retrieve data in next step's onEnter handler
step.onEnter((wzd, step) -> ageOutput.text(wzd.context().get("age", "n/a")));

Sources: showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java274-281

---

Step Types and Navigation Patterns

WizardStepType Enum

The WizardStepType enum defines four step types:

Type	Purpose	Navigation Behavior
step	Standard step	Shows in nav, enables Next button
review	Review/confirmation	Shows in nav, changes Next to "Finish"
progress	Loading/processing	Not shown in nav, adds "finished" modifier
summary	Completion message	Not shown in nav, adds "finished" modifier

Sources: components/src/main/java/org/patternfly/component/wizard/Wizard.java44-47

Navigation Modes

Standard Mode:

• All steps visible in navigation
• All steps clickable (unless manually disabled)
• Users can jump between steps freely

Progressive Mode (wizard.progressive()):

• Only current and previous steps visible in nav
• Nav items dynamically added/removed during navigation
• Must be configured before adding steps

Visit Required Mode (wizard.visitRequired()):

• All steps visible but unvisited steps are disabled
• Steps become enabled after being visited
• Prevents skipping ahead in the workflow
• Must be configured before adding steps

Sources: components/src/main/java/org/patternfly/component/wizard/Wizard.java170-195 showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java173-190

---

Step Navigation Flow

Navigation Decision Tree

Sources: components/src/main/java/org/patternfly/component/wizard/Wizard.java326-463

Method Flow in Wizard.java

Method	Triggered By	Calls	Purpose
previous()	Back button	navigateBack(previousEnabledStep)	Navigate to previous step
next()	Next button	navigateForward(nextEnabledStep) or finish()	Navigate forward or finish
select(step)	Nav item click	navigateBack() or navigateForward()	Jump to specific step
navigateBack(step)	Internal	previousHandler / previousPromise navigateTo()	Execute previous validation
navigateForward(step)	Internal	forwardThen(() -> navigateTo())	Execute next validation
forwardThen(callback)	Internal	nextHandler / nextPromise callback	Validate then execute callback
navigateTo(step)	Internal	leaveHandler update state enterHandler stepChangeHandlers	Perform actual navigation

Sources: components/src/main/java/org/patternfly/component/wizard/Wizard.java326-463

---

Handlers and Validation

Handler Types

Sources: components/src/main/java/org/patternfly/component/wizard/WizardStep.java135-216

Validation Example: Form Step

From the showcase's "Form validation" example, steps use handlers to validate input:

Setup Pattern:

1. Define form controls and validation helper text
2. Create validation logic in a BiConsumer<TextInput, String>
3. Attach handler to step with step.nextIf(handler)
4. In handler, validate input and return true/false
5. Update UI (validation status, helper text, button state)
6. Store validated data in onLeave handler

Code Flow:

WizardStep.nextIf(handler)
   User clicks Next
   WizardFooter.nextButton onClick
   Wizard.next()
   Wizard.navigateForward(nextStep)
   Wizard.forwardThen(callback)
   current.nextHandler.onNext(wizard, current, next)
   returns boolean (validation result)
   if true: callback.call()  navigateTo(nextStep)
   if false: stay on current step

Sources: showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java243-283 components/src/main/java/org/patternfly/component/wizard/Wizard.java405-424

Promise Example: Async Processing

The showcase's "Handlers and promises" example demonstrates promise usage for simulated cooking workflow:

Promise Pattern:

1. Define WizardStepNextPromise that returns Promise<Boolean>
2. In promise handler, disable buttons via footer.disableButtons()
3. Perform async operation (e.g., setInterval for progress simulation)
4. Resolve promise with true/false based on success
5. Promise's finally_() re-enables buttons via footer.updateButtons()

Sources: showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java452-470

---

Step Status and Custom Button Names

Validation Status

Steps can display visual status indicators in the navigation:

Status changes update both the step and its corresponding WizardNavItem, adding status icons and CSS modifiers.

Sources: components/src/main/java/org/patternfly/component/wizard/WizardStep.java250-260 showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java325-353

Custom Button Names

Each step can override default button labels:

The WizardFooter.updateButtons() method checks current.customButtonNames map and applies overrides.

Sources: components/src/main/java/org/patternfly/component/wizard/WizardStep.java111-114 components/src/main/java/org/patternfly/component/wizard/WizardFooter.java101-126

---

Modal Integration

The Modal class provides first-class wizard support via the addWizard(Wizard) method.

Integration Mechanics

Modal-Wizard Integration Pattern:

Automatic Behaviors:

1. Modal's close button is hidden (hideClose = true)
2. Wizard cancel handler triggers modal.close()
3. Wizard finish handler triggers modal.close()
4. Wizard navigation is constrained to modal dimensions

Sources: components/src/main/java/org/patternfly/component/modal/Modal.java228-238 showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java305-323

---

Component Lifecycle

Initialization Sequence

Navigation Sequence

Sources: components/src/main/java/org/patternfly/component/wizard/Wizard.java326-463

---

Common Usage Patterns

Basic Wizard

Sources: showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java136-152

Progressive Wizard with Auto-Progress

Sources: showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java192-241

Validation with Form

Sources: showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java243-283

---

Key Implementation Details

Linked List Management

The wizard maintains a doubly-linked list of steps using WizardStep.previous and WizardStep.next fields. This enables efficient sequential navigation without array indexing.

head  step1  step2  step3  tail
       
     current

Sources: components/src/main/java/org/patternfly/component/wizard/Wizard.java86-89 components/src/main/java/org/patternfly/component/wizard/WizardStep.java76-77

Component Lookup Pattern

Sub-components (WizardStep, WizardNavItem, WizardFooter) use lookupComponent() to find their parent Wizard instance. This is enabled by Wizard.storeComponent() in the constructor.

Sources: components/src/main/java/org/patternfly/component/wizard/Wizard.java113 components/src/main/java/org/patternfly/component/wizard/WizardStep.java283-295

Progressive Nav Management

In progressive mode, nav items are dynamically added/removed during navigation:

• Moving forward: Adds nav items for newly revealed steps
• Moving backward: Removes nav items for steps after the target

Sources: components/src/main/java/org/patternfly/component/wizard/Wizard.java429-444

Footer Button State Logic

The WizardFooter.updateButtons() method implements button state logic:

Condition	Back Button	Next Button	Next Text
current == head	Disabled	Enabled	Custom or "Next"
current == tail or type == review	Enabled	Enabled	Custom or "Finish"
Middle step	Enabled	Enabled	Custom or "Next"

Sources: components/src/main/java/org/patternfly/component/wizard/WizardFooter.java101-126

---

File Reference Summary

Core Classes:

• components/src/main/java/org/patternfly/component/wizard/Wizard.java64-508 - Main wizard component
• components/src/main/java/org/patternfly/component/wizard/WizardStep.java46-296 - Individual step component
• components/src/main/java/org/patternfly/component/wizard/WizardNav.java - Navigation sidebar
• components/src/main/java/org/patternfly/component/wizard/WizardNavItem.java52-181 - Navigation link
• components/src/main/java/org/patternfly/component/wizard/WizardFooter.java35-127 - Footer with buttons

Handler Interfaces:

• components/src/main/java/org/patternfly/component/wizard/WizardStepChangeHandler.java18-40 - Step change notification
• Step-level handlers defined in components/src/main/java/org/patternfly/component/wizard/WizardStep.java78-83

Examples:

• showcase/src/main/java/org/patternfly/showcase/component/WizardComponent.java132-638 - Comprehensive showcase with 8+ examples

Modal Integration:

• components/src/main/java/org/patternfly/component/modal/Modal.java228-238 - Wizard integration in Modal