Wizard

A wizard is a guided workflow that helps users complete complex tasks, create objects, or follow a series of steps.

Examples

Basic

The content of this step overflows and creates a scrollbar, which causes a tabindex of "0", a role of "region", and an aria-label or aria-labelledby to be applied.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer bibendum in neque nec pharetra. Duis lacinia vel sapien ut imperdiet. Nunc ultrices mollis dictum. Duis tempus, massa nec tincidunt tempor, enim ex porttitor odio, eu facilisis dolor tortor id sapien. Etiam sit amet molestie lacus. Nulla facilisi. Duis eget finibus ipsum. Quisque dictum enim sed sodales porta. Curabitur eget orci eu risus posuere pulvinar id nec turpis. Morbi mattis orci vel posuere tincidunt. Fusce bibendum et libero a auctor.

Proin elementum commodo sodales. Quisque eget libero mattis, ornare augue at, egestas nisi. Mauris ultrices orci fringilla pretium mattis. Aliquam erat volutpat. Sed pharetra condimentum dui, nec bibendum ante. Vestibulum sollicitudin, sem accumsan pharetra molestie, purus turpis lacinia lorem, commodo sodales quam lectus a urna. Nam gravida, felis a lacinia varius, ex ipsum ultrices orci, non egestas diam velit in mi. Ut sit amet commodo orci. Duis sed diam odio. Duis mi metus, dignissim in odio nec, ornare aliquet libero. Sed luctus elit nibh. Quisque et felis diam. Integer ac metus dolor.

Focus content on next/back

To focus the main content element of the Wizard, pass in the shouldFocusContent property. It is recommended that this is passed in so that users can navigate through a WizardStep content in order.

Step 1 content

Basic with disabled steps

Step 1 content

Anchors for nav items

Step 1: Read about PF3

Incrementally enabled steps

Step 1 content

Expandable steps

Progress after submission

Step 1 content

Enabled on form validation

Information content

Validate on button press

Step 1 content

Progressive steps

Get started content

Get current step

Step 1 content

Step drawer content

Step 1 content

Header

Step 1 content

Custom footer

Toggle step visibility

Toggle visibility of the next step

Step status

Step 1 content

Hooks

useWizardContext

Used to access any property of WizardContext:

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

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

useWizardFooter

Used to set a unique footer for the wizard on any given step.

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

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

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
Name	Type	Default	Description
childrenrequired	React.ReactNode		Step components
className	string		Additional classes spread to the wizard
footer	WizardFooterType		Wizard footer
header	React.ReactNode		Wizard header
height	number \| string		Custom height of the wizard
isProgressive	boolean	false	Progressively shows steps, where all steps following the active step are hidden. Defaults to false.
isVisitRequired	boolean	false	Disables steps that haven't been visited. Defaults to false.
nav	WizardNavType		Wizard navigation
navAriaLabel	string		Aria-label for the Nav
onClose	(event: React.MouseEvent<HTMLButtonElement>) => void		Callback function to close the wizard
onSave	(event: React.MouseEvent<HTMLButtonElement>) => void \| Promise<void>		Callback function to save at the end of the wizard, if not specified uses onClose
onStepChange	( event: React.MouseEvent<HTMLButtonElement>, currentStep: WizardStepType, prevStep: WizardStepType, scope: WizardStepChangeScope ) => void \| Promise<void>		Callback function when navigating between steps
shouldFocusContent	boolean	true	Flag indicating whether the wizard content should be focused after the onNext or onBack callbacks are called.
startIndex	number	1	The initial index the wizard is to start on (1 or higher). Defaults to 1.
width	number \| string		Custom 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
Name	Type	Description
activeSteprequired	WizardStepType	The active step
onBackrequired	(event: React.MouseEvent<HTMLButtonElement>) => void \| Promise<void>	Back button callback
onCloserequired	(event: React.MouseEvent<HTMLButtonElement>) => void	Cancel link callback
onNextrequired	(event: React.MouseEvent<HTMLButtonElement>) => void \| Promise<void>	Next button callback
backButtonProps	Omit<WizardFooterButtonProps, 'isDisabled'>	Additional props for the Back button.
backButtonText	React.ReactNode	Custom text for the Back button
cancelButtonProps	WizardFooterButtonProps	Additional props for the Cancel button.
cancelButtonText	React.ReactNode	Custom text for the Cancel link
className	string	Additional classes spread to the wizard footer
isBackDisabled	boolean	Flag to disable the back button
isBackHidden	boolean	Flag to hide the back button
isCancelHidden	boolean	Flag to hide the cancel button
isNextDisabled	boolean	Flag to disable the next button
nextButtonProps	Omit<WizardFooterButtonProps, 'isDisabled' \| 'type'>	Additional props for the Next button.
nextButtonText	React.ReactNode	Custom text for the Next button. The current step's nextButtonText takes precedence.

WizardFooterWrapper

Applies default wizard footer styling any number of child elements.
*required
Name	Type	Default	Description
childrenrequired	React.ReactNode
className	string

WizardToggle

Used to toggle between step content, including the body and footer. This is also where the navigation and its expandability is controlled.
*required
Name	Type	Default	Description
activeSteprequired	WizardStepType		The current step
footerrequired	React.ReactElement		Wizard footer
navrequired	React.ReactElement<WizardNavProps>		Wizard navigation
stepsrequired	WizardStepType[]		List of steps and/or sub-steps
aria-label	string	'Wizard toggle'	The expandable dropdown button's aria-label
isNavExpanded	boolean		Flag to determine whether the dropdown navigation is expanded
toggleNavExpanded	(event: React.MouseEvent<HTMLButtonElement> \| KeyboardEvent) => void		Callback to expand or collapse the dropdown navigation

WizardStep

The primary child component for Wizard. Step props are used for the list of steps managed in context.
*required
Name	Type	Description
idrequired	string \| number	Unique identifier
namerequired	React.ReactNode	Name of the step's navigation item
body	Omit<Omit<WizardBodyProps, 'children'>, 'children'>	Props for WizardBody that wraps content by default.
children	React.ReactNode \| undefined	Optional for when the step is used as a parent to sub-steps
footer	React.ReactElement \| Partial<WizardFooterProps>	Replaces the step's footer. The step's footer takes precedance over the wizard's footer.
isDisabled	boolean	Flag to disable the step's navigation item
isExpandable	boolean	Flag to determine whether parent steps can expand or not. Defaults to false.
isHidden	boolean	Flag to determine whether the step is hidden
navItem	WizardNavItemType	Replaces the step's navigation item or its properties.
status	'default' \| 'error' \| 'success'	Used to determine icon next to the step's navigation item
steps	React.ReactElement<WizardStepProps>[]	Optional list of sub-steps

WizardBody

Used as a wrapper for WizardStep content, where the wrapping element is customizable.
*required
Name	Type	Default	Description
childrenrequired	React.ReactNode		Anything that can be rendered in the Wizard body
aria-label	string		Adds an accessible name to the wrapper element when the content overflows and renders a scrollbar.
aria-labelledby	string		Adds an accessible name to the wrapper element by passing the the id of one or more elements. The aria-labelledby will only be applied when the content overflows and renders a scrollbar.
className	string		Additional classes spread to the wizard body
component	React.ElementType	'div'	Component used as the wrapping content container
hasNoPadding	boolean	false	Flag to remove the default body padding

WizardHeader

*required
Name	Type	Default	Description
titlerequired	string		Title of the wizard
className	string		Additional classes spread to the wizard header
closeButtonAriaLabel	string		Aria-label applied to the X (Close) button
description	React.ReactNode		Description of the wizard
descriptionComponent	'div' \| 'p'	'div'	Component type of the description
descriptionId	string		id for the description
isCloseHidden	boolean		Flag indicating whether the close button should be in the header
onClose	(event: React.MouseEvent<HTMLButtonElement>) => void	() => undefined	Callback function called when the X (Close) button is clicked
titleId	string		id for the title

WizardNav

*required
Name	Type	Default	Description
aria-label	string		Aria-label applied to the navigation element
aria-labelledby	string		Sets the aria-labelledby attribute on the navigation element
children	any		children should be WizardNavItem components
className	string		Additional classes spread to the wizard nav
isExpanded	boolean	false	Whether the navigation is expanded
isInnerList	boolean	false	True to return the inner list without the wrapping navigation element

WizardNavItem

*required
Name	Type	Default	Description
stepIndexrequired	number		The step index passed into the onNavItemClick callback
children	React.ReactNode	null	Can nest a WizardNav component for substeps
className	string		Additional classes spread to the wizard nav item
component	'button' \| 'a'	'button'	Component used to render WizardNavItem
content	React.ReactNode	''	The content to display in the navigation item
href	string		An optional url to use for when using an anchor component
id	string \| number		The id for the navigation item
isCurrent	boolean	false	Whether the navigation item is the currently active item
isDisabled	boolean	false	Whether the navigation item is disabled
isExpandable	boolean	false	Flag indicating that this NavItem has child steps and is expandable
isVisited	boolean	false	Whether the navigation item has been visited
onClick	(event: React.MouseEvent<HTMLButtonElement> \| React.MouseEvent<HTMLAnchorElement>, index: number) => any		Callback for when the navigation item is clicked
ouiaSafe	No type info	true
status	'default' \| 'error' \| 'success'	'default'	Used to determine the icon displayed next to content. Default has no icon.
target	React.HTMLAttributeAnchorTarget		Where to display the linked URL when using an anchor component

WizardContextProps

*required
Name	Type	Description
activeSteprequired	WizardStepType	Current step
closerequired	() => void	Close the wizard
footerrequired	React.ReactElement	Footer element
getSteprequired	(stepId: number \| string) => WizardStepType	Get step by ID
goToNextSteprequired	() => void \| Promise<void>	Navigate to the next step
goToPrevSteprequired	() => void \| Promise<void>	Navigate to the previous step
goToStepByIdrequired	(id: number \| string) => void	Navigate to step by ID
goToStepByIndexrequired	(index: number) => void	Navigate to step by index
goToStepByNamerequired	(name: string) => void	Navigate to step by name
mainWrapperRefrequired	React.RefObject<HTMLElement>	Ref for main wizard content element.
setFooterrequired	(footer: React.ReactElement \| Partial<WizardFooterProps>) => void	Update the footer with any react element
setSteprequired	(step: Pick<WizardStepType, 'id'> & Partial<WizardStepType>) => void	Set step by ID
shouldFocusContentrequired	boolean	Flag indicating whether the wizard content should be focused after the onNext or onBack callbacks are called.
stepsrequired	WizardStepType[]	List of steps

WizardBasicStep

Type used to define 'basic' steps, or in other words, steps that are neither parents or children of parents.
*required
Name	Type	Description
idrequired	string \| number	Unique identifier
indexrequired	number	Order index of step (starts at 1)
namerequired	React.ReactNode	Name of the step's navigation item
component	React.ReactElement	Content shown when the step's navigation item is selected. When treated as a parent step, only sub-step content will be shown.
footer	React.ReactElement \| Partial<WizardFooterProps>	Replaces the step's footer. The step's footer takes precedance over the wizard's footer.
isDisabled	boolean	Flag to disable the step's navigation item
isHidden	boolean	Flag to determine whether the step is hidden
isVisited	boolean	Flag to represent whether the step has been visited (navigated to)
navItem	WizardNavItemType	Replaces the step's navigation item or its properties.
status	'default' \| 'error' \| 'success'	Used to determine icon next to the step's navItem

WizardParentStep

Type used to define parent steps.
*required
Name	Type	Default	Description
subStepIdsrequired	(string \| number)[]		Nested step IDs
isExpandable	boolean		Flag to determine whether the step can expand or not.

WizardSubStep

Type used to define sub-steps.
*required
Name	Type	Default	Description
parentIdrequired	string \| number		Unique identifier of the parent step

CSS variables

Expand or collapse column	Selector	Variable	Value

View source on GitHub

Wizard

Examples

Basic

Focus content on next/back

Basic with disabled steps

Anchors for nav items

Incrementally enabled steps

Expandable steps

Progress after submission

Enabled on form validation

Validate on button press

Progressive steps

Get current step

Step drawer content

Custom navigation

Header

You're a wizard, Harry

Custom footer

Custom navigation item

Toggle step visibility

Step status

Hooks

useWizardContext

useWizardFooter

Props

Wizard

WizardFooter

WizardFooterWrapper

WizardToggle

WizardStep

WizardBody

WizardHeader

WizardNav

WizardNavItem

WizardContextProps

WizardBasicStep

WizardParentStep

WizardSubStep

CSS variables

Wizard

Examples

Basic

Focus content on next/back

Basic with disabled steps

Anchors for nav items

Incrementally enabled steps

Expandable steps

Progress after submission

Enabled on form validation

Validate on button press

Progressive steps

Get current step

Within modal

Step drawer content

Custom navigation

Header

You're a wizard, Harry

Custom footer

Custom navigation item

Toggle step visibility

Step status

Hooks

useWizardContext

useWizardFooter

Props

Wizard

WizardFooter

WizardFooterWrapper

WizardToggle

WizardStep

WizardBody

WizardHeader

WizardNav

WizardNavItem

WizardContextProps

WizardBasicStep

WizardParentStep

WizardSubStep

CSS variables