Skip to content
Patternfly Logo

Wizard

A wizard provides a guided workflow that offers a path to complete a task, create an object or objects, or finish a series of steps for some other outcome. Wizards should incite trust in the user and guide them through an otherwise overwhelming experience.

A newer React implementation of the wizard will replace the existing implementation at the next major release. The documentation for the newer implementation is under the React next tab, and this newer implementation can be imported from @patternfly/react-core/next.

Info alert:Beta feature

This beta component is currently under review and is still open for further evolution. It is available for use in product. Beta components are considered for promotion on a quarterly basis. Please join in and give us your feedback or submit any questions on the PatternFly forum or via Slack. To learn more about the process, visit our about page or our Beta components page on GitHub.

PatternFly has two implementations of a Wizard. This newer Wizard takes a more explicit and declarative approach compared to the older implementation, which can be found under the React tab.

Examples

Basic

Step 1 content

Custom navigation

The Wizard's nav property can be used to build your own navigation.

/** Callback for the Wizard's 'nav' property. Returns element which replaces the Wizard's default navigation. */ export type CustomWizardNavFunction = ( isOpen: boolean, steps: WizardControlStep[], activeStep: WizardControlStep, goToStepByIndex: (index: number) => void ) => React.ReactElement<WizardNavProps>; /** Encompasses all step type variants that are internally controlled by the Wizard */ type WizardControlStep = WizardBasicStep | WizardParentStep | WizardSubStep;

Did you say...custom nav?

Kitchen sink

Includes a header, custom footer, sub-steps, step content with a drawer, custom nav item, and nav prevention until step visitation.

Custom operations when navigating between steps can be achieved by utilizing onNext, onBack or onNavByIndex properties whose callback functions return the 'id' and 'name' of the currently focused step (currentStep), and the previously focused step (previousStep).

/** Callback for the Wizard's 'onNext', 'onBack', and 'onNavByIndex' properties */ type WizardNavStepFunction = (currentStep: WizardNavStepData, previousStep: WizardNavStepData) => void; /** Data returned for either parameter of WizardNavStepFunction */ type WizardNavStepData = Pick<WizardControlStep, 'id' | 'name'>;

You're a wizard, Harry

Hooks

useWizardFooter

Used to set a unique footer for the wizard on any given step. See step 3 of Kitchen sink for a live example.

import { useWizardFooter } from '@patternfly/react-core/next';

const StepContent = () => {
  useWizardFooter(<>Some footer</>);
  return <>Step content</>;
}

useWizardContext

Used to access any property of WizardContext:

import { useWizardContext } from '@patternfly/react-core/next';

const StepContent = () => {
  const { activeStep } = useWizardContext();
  return <>This is the active step: {activeStep}</>;
}

Props

Wizard

Wrapper for all steps and hosts state, including navigation helpers, within context. The WizardContext provided by default gives any child of wizard access to those resources.
*required
NameTypeDefaultDescription
childrenrequiredReact.ReactElement<WizardStepProps> | React.ReactElement<WizardStepProps>[]Step components
classNamestringAdditional classes spread to the wizard
footerDefaultWizardFooterProps | React.ReactElementWizard footer
headerReact.ReactNodeWizard header
heightnumber | stringCustom height of the wizard
navDefaultWizardNavProps | CustomWizardNavFunctionDefault wizard nav props or a custom WizardNav (with callback)
onBackWizardNavStepFunctionCallback function after back button is clicked
onClose() => voidCallback function to close the wizard
onNavByIndexWizardNavStepFunctionCallback function when a step in the nav is clicked
onNextWizardNavStepFunctionCallback function after next button is clicked
onSave() => voidCallback function to save at the end of the wizard, if not specified uses onClose
startIndexnumberThe initial index the wizard is to start on (1 or higher). Defaults to 1.
widthnumber | stringCustom width of the wizard

WizardFooter

Hosts the standard structure of a footer with ties to the active step so that text for buttons can vary from step to step.
*required
NameTypeDefaultDescription
activeSteprequiredWizardControlStepThe currently active WizardStep
onBackrequired() => WizardNavStepFunction | voidBack button callback
onCloserequired() => voidCancel link callback
onNextrequired() => WizardNavStepFunction | voidNext button callback
backButtonTextReact.ReactNode'Back'Custom text for the Back button
cancelButtonTextReact.ReactNode'Cancel'Custom text for the Cancel link
disableBackButtonbooleanOptional flag to disable the first step's back button
nextButtonTextReact.ReactNode'Next'Custom text for the Next button. The activeStep's nextButtonText takes precedence.

WizardToggle

Used to toggle between step content, including the body and footer. This is also where the nav and its expandability is controlled.
*required
NameTypeDefaultDescription
activeSteprequiredWizardControlStepThe currently active WizardStep
footerrequiredReact.ReactElementThe WizardFooter
goToStepByIndexrequired(index: number) => voidNavigate using the step index
navrequiredDefaultWizardNavProps | CustomWizardNavFunctionCustom WizardNav or callback used to create a default WizardNav
stepsrequiredWizardControlStep[]List of steps and/or sub-steps
aria-labelstring'Wizard toggle'The button's aria-label
unmountInactiveStepsbooleantrueFlag to unmount inactive steps instead of hiding. Defaults to true

WizardStep

Used as a passthrough of step properties for Wizard and all supporting child components. Also acts as a wrapper for content, with an optional inclusion of WizardBody.
*required
NameTypeDefaultDescription
bodyWizardBodyProps | nullProps for WizardBody that wraps content by default. Can be set to null for exclusion of WizardBody.
childrenReact.ReactNodeOptional for when the step is used as a parent to sub-steps
stepsReact.ReactElement<WizardStepProps>[]Optional list of sub-steps

WizardBody

Used as a wrapper for WizardStep content, where the wrapping element is customizable.
*required
NameTypeDefaultDescription
aria-labelstringAn aria-label to use for the wrapper element
aria-labelledbystringSets the aria-labelledby attribute for the wrapper element
childrenReact.ReactNode | React.ReactNode[]
hasNoBodyPaddingbooleanfalseSet to true to remove the default body padding
wrapperElementReact.ElementType'div'Component used as the wrapping content container

WizardHeader

*required
NameTypeDefaultDescription
titlerequiredstringTitle of the wizard
closeButtonAriaLabelstringAria-label applied to the X (Close) button
descriptionReact.ReactNodeDescription of the wizard
descriptionComponent'div' | 'p''p'Component type of the description
descriptionIdstringid for the description
hideClosebooleanFlag indicating whether the close button should be in the header
onClose() => void() => undefinedCallback function called when the X (Close) button is clicked
titleIdstringid for the title

WizardNav

*required
NameTypeDefaultDescription
aria-labelstringAria-label applied to the nav element
aria-labelledbystringSets the aria-labelledby attribute on the nav element
childrenanychildren should be WizardNavItem components
isOpenbooleanfalseWhether the nav is expanded
returnListbooleanfalseTrue to return the inner list without the wrapping nav element

WizardNavItem

*required
NameTypeDefaultDescription
steprequirednumberThe step passed into the onNavItemClick callback
childrenReact.ReactNodenullCan nest a WizardNav component for substeps
contentReact.ReactNode''The content to display in the nav item
hrefstringnullAn optional url to use for when using an anchor component
idstring | numberThe id for the nav item
isCurrentbooleanfalseWhether the nav item is the currently active item
isDisabledbooleanfalseWhether the nav item is disabled
isExpandablebooleanfalseFlag indicating that this NavItem has child steps and is expandable
navItemComponent'button' | 'a''button'Component used to render WizardNavItem
onNavItemClick(step: number) => any() => undefinedCallback for when the nav item is clicked

WizardContextProps

*required
NameTypeDefaultDescription
activeSteprequiredWizardControlStepActive step
footerrequiredReact.ReactElementFooter element
goToStepByIdrequired(id: number | string) => voidNavigate to step by ID
goToStepByIndexrequired(index: number) => voidNavigate to step by index
goToStepByNamerequired(name: string) => voidNavigate to step by name
onBackrequired() => voidNavigate to the previous step
onCloserequired() => voidClose the wizard
onNextrequired() => voidNavigate to the next step
setFooterrequired(footer: React.ReactElement) => voidUpdate the footer with any react element
stepsrequiredWizardControlStep[]List of steps

WizardBasicStep

Type used to define 'basic' steps, or in other words, steps that are neither parents or children of parents.
*required
NameTypeDefaultDescription
idrequiredstring | numberUnique identifier
namerequiredReact.ReactNodeName of the step's nav item
componentReact.ReactElementContent shown when the step's nav item is selected. When treated as a parent step, only sub-step content will be shown.
disableNextboolean(Unused if footer is controlled) The condition needed to disable the Next button
hideBackButtonboolean(Unused if footer is controlled) True to hide the Back button
hideCancelButtonboolean(Unused if footer is controlled) True to hide the Cancel button
isDisabledbooleanFlag to disable the step's nav item
navItemReact.ReactElement<WizardNavItemProps>(Unused if nav is controlled) Custom WizardNavItem
nextButtonTextReact.ReactNode(Unused if footer is controlled) Can change the Next button text. If nextButtonText is also set for the Wizard, this step specific one overrides it.
visitedbooleanFlag to represent whether the step has been visited (navigated to)

WizardParentStep

Type used to define parent steps.
*required
NameTypeDefaultDescription
subStepIdsrequiredstring[]Nested step IDs

WizardSubStep

Type used to define sub-steps.
*required
NameTypeDefaultDescription
parentIdrequiredstring | numberUnique identifier of the parent step

DefaultWizardNavProps

Used to customize aspects of the Wizard's default navigation.
*required
NameTypeDefaultDescription
ariaLabelstringAria-label for the Nav
ariaLabelledBystringSets aria-labelledby on nav element
forceStepVisitbooleanDisable step nav items until they are visited
isExpandablebooleanFlag indicating nav items with sub steps are expandable

DefaultWizardFooterProps

Used to customize aspects of the Wizard's default footer.
*required
NameTypeDefaultDescription
backButtonTextReact.ReactNodeThe Back button text
cancelButtonTextReact.ReactNodeThe Cancel button text
nextButtonTextReact.ReactNodeThe Next button text

CSS variables

.pf-c-wizard__header--pf-global--Color--100
#fff
.pf-c-wizard__header--pf-global--Color--200
#f0f0f0
.pf-c-wizard__header--pf-global--BorderColor--100
#b8bbbe
.pf-c-wizard__header--pf-global--primary-color--100
#73bcf7
.pf-c-wizard__header--pf-global--link--Color
#2b9af3
.pf-c-wizard__header--pf-global--link--Color--hover
#2b9af3
.pf-c-wizard__header--pf-global--BackgroundColor--100
#151515
.pf-c-wizard__header .pf-c-card--pf-c-card--BackgroundColor
rgba(#030303, .32)
.pf-c-wizard__header .pf-c-button--pf-c-button--m-primary--Color
#06c
.pf-c-wizard__header .pf-c-button--pf-c-button--m-primary--hover--Color
#06c
.pf-c-wizard__header .pf-c-button--pf-c-button--m-primary--focus--Color
#06c
.pf-c-wizard__header .pf-c-button--pf-c-button--m-primary--active--Color
#06c
.pf-c-wizard__header .pf-c-button--pf-c-button--m-primary--BackgroundColor
#fff
.pf-c-wizard__header .pf-c-button--pf-c-button--m-primary--hover--BackgroundColor
#f0f0f0
.pf-c-wizard__header .pf-c-button--pf-c-button--m-primary--focus--BackgroundColor
#f0f0f0
.pf-c-wizard__header .pf-c-button--pf-c-button--m-primary--active--BackgroundColor
#f0f0f0
.pf-c-wizard__header .pf-c-button--pf-c-button--m-secondary--Color
#fff
.pf-c-wizard__header .pf-c-button--pf-c-button--m-secondary--hover--Color
#fff
.pf-c-wizard__header .pf-c-button--pf-c-button--m-secondary--focus--Color
#fff
.pf-c-wizard__header .pf-c-button--pf-c-button--m-secondary--active--Color
#fff
.pf-c-wizard__header .pf-c-button--pf-c-button--m-secondary--BorderColor
#fff
.pf-c-wizard__header .pf-c-button--pf-c-button--m-secondary--hover--BorderColor
#fff
.pf-c-wizard__header .pf-c-button--pf-c-button--m-secondary--focus--BorderColor
#fff
.pf-c-wizard__header .pf-c-button--pf-c-button--m-secondary--active--BorderColor
#fff
.pf-c-wizard--pf-c-wizard--Height
100%
.pf-c-wizard--pf-c-modal-box--c-wizard--FlexBasis
47.625rem
.pf-c-wizard--pf-c-wizard__header--BackgroundColor
#151515
.pf-c-wizard--pf-c-wizard__header--ZIndex
300
.pf-c-wizard--pf-c-wizard__header--PaddingTop
1.5rem
.pf-c-wizard--pf-c-wizard__header--PaddingRight
1rem
.pf-c-wizard--pf-c-wizard__header--PaddingBottom
1.5rem
.pf-c-wizard--pf-c-wizard__header--PaddingLeft
1rem
.pf-c-wizard--pf-c-wizard__header--lg--PaddingRight
1rem
.pf-c-wizard--pf-c-wizard__header--lg--PaddingLeft
1rem
.pf-c-wizard--pf-c-wizard__header--xl--PaddingRight
1.5rem
.pf-c-wizard--pf-c-wizard__header--xl--PaddingLeft
1.5rem
.pf-c-wizard--pf-c-wizard__close--Top
calc(1.5rem - 0.375rem)
.pf-c-wizard--pf-c-wizard__close--Right
0
.pf-c-wizard--pf-c-wizard__close--xl--Right
1.5rem
.pf-c-wizard--pf-c-wizard__close--FontSize
1.25rem
.pf-c-wizard--pf-c-wizard__title--PaddingRight
3rem
.pf-c-wizard--pf-c-wizard__description--PaddingTop
0.5rem
.pf-c-wizard--pf-c-wizard__description--Color
#f0f0f0
.pf-c-wizard--pf-c-wizard__nav-link--Color
#151515
.pf-c-wizard--pf-c-wizard__nav-link--TextDecoration
none
.pf-c-wizard--pf-c-wizard__nav-link--hover--Color
#06c
.pf-c-wizard--pf-c-wizard__nav-link--focus--Color
#06c
.pf-c-wizard--pf-c-wizard__nav-link--m-current--Color
#06c
.pf-c-wizard--pf-c-wizard__nav-link--m-current--FontWeight
400
.pf-c-wizard--pf-c-wizard__nav-link--m-disabled--Color
#6a6e73
.pf-c-wizard--pf-c-wizard__nav-list__nav-list__nav-link--m-current--FontWeight
400
.pf-c-wizard--pf-c-wizard__nav-link-toggle--PaddingRight
0.5rem
.pf-c-wizard--pf-c-wizard__nav-link-toggle--PaddingLeft
0.5rem
.pf-c-wizard--pf-c-wizard__nav-link-toggle--Color
#6a6e73
.pf-c-wizard--pf-c-wizard__nav-link--hover__nav-link-toggle-icon--Color
#151515
.pf-c-wizard--pf-c-wizard__nav-link--focus__nav-link-toggle-icon--Color
#151515
.pf-c-wizard--pf-c-wizard__nav-link-toggle-icon--Transition
all 250ms cubic-bezier(.42, 0, .58, 1)
.pf-c-wizard--pf-c-wizard__nav-link-toggle-icon--Rotate
0
.pf-c-wizard--pf-c-wizard__nav-item--m-expanded__link-toggle-icon--Rotate
90deg
.pf-c-wizard--pf-c-wizard__nav-link--before--Width
1.5rem
.pf-c-wizard--pf-c-wizard__nav-link--before--Height
1.5rem
.pf-c-wizard--pf-c-wizard__nav-link--before--Top
0
.pf-c-wizard--pf-c-wizard__nav-link--before--BackgroundColor
#f0f0f0
.pf-c-wizard--pf-c-wizard__nav-link--before--BorderRadius
30em
.pf-c-wizard--pf-c-wizard__nav-link--before--Color
#151515
.pf-c-wizard--pf-c-wizard__nav-link--before--FontSize
0.875rem
.pf-c-wizard--pf-c-wizard__nav-link--before--TranslateX
calc(-100% - 0.5rem)
.pf-c-wizard--pf-c-wizard__nav-link--m-current--before--BackgroundColor
#06c
.pf-c-wizard--pf-c-wizard__nav-link--m-current--before--Color
#fff
.pf-c-wizard--pf-c-wizard__nav-link--m-disabled--before--BackgroundColor
transparent
.pf-c-wizard--pf-c-wizard__nav-link--m-disabled--before--Color
#6a6e73
.pf-c-wizard--pf-c-wizard__toggle--BackgroundColor
#fff
.pf-c-wizard--pf-c-wizard__toggle--ZIndex
300
.pf-c-wizard--pf-c-wizard__toggle--BoxShadow
0 0.5rem 0.5rem -0.375rem rgba(3, 3, 3, 0.18)
.pf-c-wizard--pf-c-wizard__toggle--PaddingTop
1.5rem
.pf-c-wizard--pf-c-wizard__toggle--PaddingRight
1rem
.pf-c-wizard--pf-c-wizard__toggle--PaddingBottom
1.5rem
.pf-c-wizard--pf-c-wizard__toggle--PaddingLeft
calc(1rem + 1.5rem + 0.5rem)
.pf-c-wizard--pf-c-wizard__toggle--m-expanded--BorderBottomWidth
1px
.pf-c-wizard--pf-c-wizard__toggle--m-expanded--BorderBottomColor
#d2d2d2
.pf-c-wizard--pf-c-wizard--m-in-page__toggle--xl--PaddingLeft
calc(2rem + 1.5rem + 0.5rem)
.pf-c-wizard--pf-c-wizard__toggle-num--before--Top
0
.pf-c-wizard--pf-c-wizard__toggle-list-item--not-last-child--MarginRight
0.5rem
.pf-c-wizard--pf-c-wizard__toggle-list-item--MarginBottom
0.25rem
.pf-c-wizard--pf-c-wizard__toggle-list--MarginRight
0.5rem
.pf-c-wizard--pf-c-wizard__toggle-list--MarginBottom
calc(0.25rem * -1)
.pf-c-wizard--pf-c-wizard__toggle-separator--MarginLeft
0.5rem
.pf-c-wizard--pf-c-wizard__toggle-separator--Color
#8a8d90
.pf-c-wizard--pf-c-wizard__toggle-icon--LineHeight
1.5
.pf-c-wizard--pf-c-wizard__toggle--m-expanded__toggle-icon--Rotate
180deg
.pf-c-wizard--pf-c-wizard__nav--ZIndex
200
.pf-c-wizard--pf-c-wizard__nav--BackgroundColor
#fff
.pf-c-wizard--pf-c-wizard__nav--BoxShadow
0 0.5rem 0.5rem -0.375rem rgba(3, 3, 3, 0.18)
.pf-c-wizard--pf-c-wizard__nav--Width
100%
.pf-c-wizard--pf-c-wizard__nav--lg--Width
15.625rem
.pf-c-wizard--pf-c-wizard__nav--lg--BorderRightWidth
1px
.pf-c-wizard--pf-c-wizard__nav--lg--BorderRightColor
#d2d2d2
.pf-c-wizard--pf-c-wizard__nav-list--PaddingTop
1.5rem
.pf-c-wizard--pf-c-wizard__nav-list--PaddingRight
1rem
.pf-c-wizard--pf-c-wizard__nav-list--PaddingBottom
1.5rem
.pf-c-wizard--pf-c-wizard__nav-list--PaddingLeft
calc(1rem + 1.5rem + 0.5rem)
.pf-c-wizard--pf-c-wizard__nav-list--lg--PaddingTop
1rem
.pf-c-wizard--pf-c-wizard__nav-list--lg--PaddingRight
1rem
.pf-c-wizard--pf-c-wizard__nav-list--lg--PaddingBottom
1rem
.pf-c-wizard--pf-c-wizard__nav-list--xl--PaddingTop
1.5rem
.pf-c-wizard--pf-c-wizard__nav-list--xl--PaddingRight
1.5rem
.pf-c-wizard--pf-c-wizard__nav-list--xl--PaddingBottom
1.5rem
.pf-c-wizard--pf-c-wizard__nav-list--xl--PaddingLeft
calc(1.5rem + 1.5rem + 0.5rem)
.pf-c-wizard--pf-c-wizard__nav-list--nested--MarginLeft
1rem
.pf-c-wizard--pf-c-wizard__nav-list--nested--MarginTop
1rem
.pf-c-wizard--pf-c-wizard__nav-item--MarginTop
1rem
.pf-c-wizard--pf-c-wizard__outer-wrap--BackgroundColor
#fff
.pf-c-wizard--pf-c-wizard__outer-wrap--lg--PaddingLeft
100%
.pf-c-wizard--pf-c-wizard__outer-wrap--MinHeight
15.625rem
.pf-c-wizard--pf-c-wizard__main--ZIndex
100
.pf-c-wizard--pf-c-wizard__main-body--PaddingTop
1rem
.pf-c-wizard--pf-c-wizard__main-body--PaddingRight
1rem
.pf-c-wizard--pf-c-wizard__main-body--PaddingBottom
1rem
.pf-c-wizard--pf-c-wizard__main-body--PaddingLeft
1rem
.pf-c-wizard--pf-c-wizard__main-body--xl--PaddingTop
1.5rem
.pf-c-wizard--pf-c-wizard__main-body--xl--PaddingRight
1.5rem
.pf-c-wizard--pf-c-wizard__main-body--xl--PaddingBottom
1.5rem
.pf-c-wizard--pf-c-wizard__main-body--xl--PaddingLeft
1.5rem
.pf-c-wizard--pf-c-wizard__footer--BackgroundColor
#fff
.pf-c-wizard--pf-c-wizard__footer--ZIndex
200
.pf-c-wizard--pf-c-wizard__footer--PaddingTop
1rem
.pf-c-wizard--pf-c-wizard__footer--PaddingRight
1rem
.pf-c-wizard--pf-c-wizard__footer--PaddingBottom
0.5rem
.pf-c-wizard--pf-c-wizard__footer--PaddingLeft
1rem
.pf-c-wizard--pf-c-wizard__footer--xl--PaddingTop
1.5rem
.pf-c-wizard--pf-c-wizard__footer--xl--PaddingRight
1.5rem
.pf-c-wizard--pf-c-wizard__footer--xl--PaddingBottom
1rem
.pf-c-wizard--pf-c-wizard__footer--xl--PaddingLeft
1.5rem
.pf-c-wizard--pf-c-wizard__footer--BoxShadow
0 -0.125rem 0.25rem -0.0625rem rgba(3, 3, 3, 0.16)
.pf-c-wizard--pf-c-wizard__footer--child--MarginRight
1rem
.pf-c-wizard--pf-c-wizard__footer--child--MarginBottom
0.5rem
.pf-c-wizard--pf-c-wizard__footer-cancel--MarginLeft
calc(3rem - 1rem)
.pf-c-wizard.pf-m-finished--pf-c-wizard__outer-wrap--lg--PaddingLeft
0
.pf-c-wizard__toggle.pf-m-expanded--pf-c-wizard__toggle--BoxShadow
none
.pf-c-wizard__toggle-num--pf-c-wizard__nav-link--before--Top
0
.pf-c-wizard__toggle-num--pf-c-wizard__nav-link--before--BackgroundColor
#06c
.pf-c-wizard__toggle-num--pf-c-wizard__nav-link--before--Color
#fff
.pf-c-wizard__nav-item.pf-m-expanded > .pf-c-wizard__nav-link--pf-c-wizard__nav-link-toggle-icon--Rotate
90deg
.pf-c-wizard__nav-link:hover--pf-c-wizard__nav-link--Color
#06c
.pf-c-wizard__nav-link:hover--pf-c-wizard__nav-link-toggle--Color
#151515
.pf-c-wizard__nav-link:focus--pf-c-wizard__nav-link--Color
#06c
.pf-c-wizard__nav-link:focus--pf-c-wizard__nav-link-toggle--Color
#151515
.pf-c-wizard__nav-link.pf-m-current--pf-c-wizard__nav-link--Color
#06c
.pf-c-wizard__nav-link:disabled--pf-c-wizard__nav-link--Color
#6a6e73
.pf-c-wizard__nav-link:disabled::before--pf-c-wizard__nav-link--before--BackgroundColor
transparent
.pf-c-wizard__nav-link:disabled::before--pf-c-wizard__nav-link--before--Color
#6a6e73

View source on GitHub