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 has replaced the now deprecated implementation. The documentation for the deprecated implementation is under the React deprecated tab, and this deprecated implementation can be imported from @patternfly/react-core/deprecated.

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.

If a WizardStep is passed a body={null} property, you must manually handle focus.

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

Within modal

Step drawer content

Step 1 content

Custom navigation

Did you say...custom nav?

You're a wizard, Harry

To be clear, all those not named Harry are not wizards.
Step 1 content

Custom navigation item

Step 1 content

Toggle step visibility

Step error 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
NameTypeDefaultDescription
childrenrequiredReact.ReactNodeStep components
classNamestringAdditional classes spread to the wizard
footerWizardFooterTypeWizard footer
headerReact.ReactNodeWizard header
heightnumber | stringCustom height of the wizard
isProgressivebooleanfalseProgressively shows steps, where all steps following the active step are hidden. Defaults to false.
isVisitRequiredbooleanfalseDisables steps that haven't been visited. Defaults to false.
navWizardNavTypeWizard navigation
navAriaLabelstringAria-label for the Nav
onClose(event: React.MouseEvent<HTMLButtonElement>) => voidCallback 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
shouldFocusContentBetabooleanfalseFlag indicating whether the wizard content should be focused after the onNext or onBack callbacks are called.
startIndexnumber1The 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
activeSteprequiredWizardStepTypeThe active step
onBackrequired(event: React.MouseEvent<HTMLButtonElement>) => void | Promise<void>Back button callback
onCloserequired(event: React.MouseEvent<HTMLButtonElement>) => voidCancel link callback
onNextrequired(event: React.MouseEvent<HTMLButtonElement>) => void | Promise<void>Next button callback
backButtonPropsOmit<WizardFooterButtonProps, 'isDisabled'>Additional props for the Back button.
backButtonTextReact.ReactNodeCustom text for the Back button
cancelButtonPropsWizardFooterButtonPropsAdditional props for the Cancel button.
cancelButtonTextReact.ReactNodeCustom text for the Cancel link
isBackDisabledbooleanFlag to disable the back button
isBackHiddenbooleanFlag to hide the back button
isCancelHiddenbooleanFlag to hide the cancel button
isNextDisabledbooleanFlag to disable the next button
nextButtonPropsOmit<WizardFooterButtonProps, 'isDisabled' | 'type'>Additional props for the Next button.
nextButtonTextReact.ReactNodeCustom text for the Next button. The current step's nextButtonText takes precedence.

WizardFooterWrapper

Applies default wizard footer styling any number of child elements.
*required
NameTypeDefaultDescription
childrenrequiredReact.ReactNode

WizardToggle

Used to toggle between step content, including the body and footer. This is also where the navigation and its expandability is controlled.
*required
NameTypeDefaultDescription
activeSteprequiredWizardStepTypeThe current step
footerrequiredReact.ReactElementWizard footer
navrequiredReact.ReactElement<WizardNavProps>Wizard navigation
stepsrequiredWizardStepType[]List of steps and/or sub-steps
aria-labelstring'Wizard toggle'The expandable dropdown button's aria-label
isNavExpandedbooleanFlag to determine whether the dropdown navigation is expanded
toggleNavExpanded(event: React.MouseEvent<HTMLButtonElement> | KeyboardEvent) => voidCallback 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
NameTypeDefaultDescription
idrequiredstring | numberUnique identifier
namerequiredReact.ReactNodeName of the step's navigation item
bodyOmit<Omit<WizardBodyProps, 'children'>, 'children'> | nullProps for WizardBody that wraps content by default. Can be set to null for exclusion of WizardBody.
childrenReact.ReactNode | undefinedOptional for when the step is used as a parent to sub-steps
footerReact.ReactElement | Partial<WizardFooterProps>Replaces the step's footer. The step's footer takes precedance over the wizard's footer.
isDisabledbooleanFlag to disable the step's navigation item
isExpandablebooleanFlag to determine whether parent steps can expand or not. Defaults to false.
isHiddenbooleanFlag to determine whether the step is hidden
navItemWizardNavItemTypeReplaces the step's navigation item or its properties.
status'default' | 'error'Used to determine icon next to the step's navigation item
stepsReact.ReactElement<WizardStepProps>[]Optional list of sub-steps

WizardBody

Used as a wrapper for WizardStep content, where the wrapping element is customizable.
*required
NameTypeDefaultDescription
childrenrequiredReact.ReactNodeAnything that can be rendered in the Wizard body
aria-labelstringAdds an accessible name to the wrapper element when the content overflows and renders a scrollbar.
aria-labelledbystringAdds 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.
componentReact.ElementType'div'Component used as the wrapping content container
hasNoPaddingbooleanfalseFlag to remove the default body padding

WizardHeader

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

WizardNav

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

WizardNavItem

*required
NameTypeDefaultDescription
stepIndexrequirednumberThe step index passed into the onNavItemClick callback
childrenReact.ReactNodenullCan nest a WizardNav component for substeps
component'button' | 'a''button'Component used to render WizardNavItem
contentReact.ReactNode''The content to display in the navigation item
hrefstringAn optional url to use for when using an anchor component
idstring | numberThe id for the navigation item
isCurrentbooleanfalseWhether the navigation item is the currently active item
isDisabledbooleanfalseWhether the navigation item is disabled
isExpandablebooleanfalseFlag indicating that this NavItem has child steps and is expandable
isVisitedbooleanfalseWhether the navigation item has been visited
onClick(event: React.MouseEvent<HTMLButtonElement> | React.MouseEvent<HTMLAnchorElement>, index: number) => anyCallback for when the navigation item is clicked
ouiaSafeNo type infotrue
status'default' | 'error''default'Used to determine the icon displayed next to content. Default has no icon.
targetReact.HTMLAttributeAnchorTargetWhere to display the linked URL when using an anchor component

WizardContextProps

*required
NameTypeDefaultDescription
activeSteprequiredWizardStepTypeCurrent step
closerequired() => voidClose the wizard
footerrequiredReact.ReactElementFooter element
getSteprequired(stepId: number | string) => WizardStepTypeGet 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) => voidNavigate to step by ID
goToStepByIndexrequired(index: number) => voidNavigate to step by index
goToStepByNamerequired(name: string) => voidNavigate to step by name
mainWrapperRefrequiredReact.RefObject<HTMLElement>Ref for main wizard content element.
setFooterrequired(footer: React.ReactElement | Partial<WizardFooterProps>) => voidUpdate the footer with any react element
setSteprequired(step: Pick<WizardStepType, 'id'> & Partial<WizardStepType>) => voidSet step by ID
shouldFocusContentrequiredbooleanFlag indicating whether the wizard content should be focused after the onNext or onBack callbacks are called.
stepsrequiredWizardStepType[]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
indexrequirednumberOrder index of step (starts at 1)
namerequiredReact.ReactNodeName of the step's navigation item
componentReact.ReactElementContent shown when the step's navigation item is selected. When treated as a parent step, only sub-step content will be shown.
footerReact.ReactElement | Partial<WizardFooterProps>Replaces the step's footer. The step's footer takes precedance over the wizard's footer.
isDisabledbooleanFlag to disable the step's navigation item
isHiddenbooleanFlag to determine whether the step is hidden
isVisitedbooleanFlag to represent whether the step has been visited (navigated to)
navItemWizardNavItemTypeReplaces the step's navigation item or its properties.
status'default' | 'error'Used to determine icon next to the step's navItem

WizardParentStep

Type used to define parent steps.
*required
NameTypeDefaultDescription
subStepIdsrequired(string | number)[]Nested step IDs
isExpandablebooleanFlag to determine whether the step can expand or not.

WizardSubStep

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

CSS variables

Expand or collapse columnSelectorVariableValue

View source on GitHub