Wizard

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

Warning alert:Deprecated feature

This implementation has been deprecated in favor of a newer implementation, and is no longer getting maintained or enhanced. To learn more about the process, visit our about page.

If you seek a wizard solution that allows for more composition, see the React tab.

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.

Basic with disabled steps

Step 1 content

Anchors for nav items

Step 1: Read about PF3

Incrementally enabled steps

Step 1 content

Expandable steps

Substep A content

Finished

Step 1 content

Enabled on form validation

Step 1 content

Validate on button press

This example demonstrates how to use the WizardContextConsumer to consume the WizardContext. WizardContext can be used to imperatively move to a specific wizard step.

The definition of the WizardContext is as follows:

interface WizardContext { goToStepById: (stepId: number | string) => void; goToStepByName: (stepName: string) => void; onNext: () => void; onBack: () => void; onClose: () => void; activeStep: WizardStep; }

Step 1 content

Progressive steps

Get current step

Step 1 content

Wizard in modal

Wizard with drawer

Information step content

Props

Wizard

*required
NameTypeDefaultDescription
stepsrequiredWizardStep[]The wizard steps configuration object
appendToHTMLElement | (() => HTMLElement)nullThe parent container to append the modal to. Defaults to document.body
backButtonTextReact.ReactNode'Back'(Unused if footer is controlled) The Back button text
cancelButtonTextReact.ReactNode'Cancel'(Unused if footer is controlled) The Cancel button text
classNamestring''Additional classes spread to the Wizard
closeButtonAriaLabelstring'Close'(Unused if footer is controlled) aria-label for the close button
descriptionReact.ReactNode''The wizard description
descriptionComponent'div' | 'p''p'Component type of the description
descriptionIdstringAn optional id for the description
footerReact.ReactNodenull(Use to control the footer) Passing in a footer component lets you control the buttons yourself
hasDrawerbooleanfalseFlag indicating the wizard has a drawer for at least one of the wizard steps
hasNoBodyPaddingbooleanfalseCan remove the default padding around the main body content by setting this to true
heightnumber | stringnullCustom height of the wizard
hideClosebooleanfalseFlag indicating whether the close button should be in the header
isDrawerExpandedbooleanfalseFlag indicating the wizard drawer is expanded
isNavExpandablebooleanfalseFlag indicating nav items with sub steps are expandable
isOpenbooleanundefinedFlag indicating Wizard modal is open. Wizard will be placed into a modal if this prop is provided
mainAriaLabelstringnullAdds an accessible name to the wizard body when the body content overflows and renders a scrollbar.
mainAriaLabelledBystringnullAdds an accessible name to the wizard body by passing the the id of one or more elements. The aria-labelledby will only be applied when the body content overflows and renders a scrollbar.
navAriaLabelstringnullAria-label for the Nav
navAriaLabelledBystringnullSets aria-labelledby on nav element
nextButtonTextReact.ReactNode'Next'(Unused if footer is controlled) The Next button text
onBack( newStep: { id?: string | number; name: React.ReactNode }, prevStep: { prevId?: string | number; prevName: React.ReactNode } ) => voidnull(Unused if footer is controlled) Callback function after Back button is clicked
onClose() => void() => undefined as anyCallback function to close the wizard
onCurrentStepChanged(step: WizardStep) => voidCallback function to signal the current step in the wizard
onExpandDrawer() => void() => undefined as anyCallback function for when the drawer is toggled. Can be used to set browser focus in the drawer.
onGoToStep( newStep: { id?: string | number; name: React.ReactNode }, prevStep: { prevId?: string | number; prevName: React.ReactNode } ) => voidnullCallback function when a step in the nav is clicked
onNext( newStep: { id?: string | number; name: React.ReactNode }, prevStep: { prevId?: string | number; prevName: React.ReactNode } ) => voidnull(Unused if footer is controlled) Callback function after Next button is clicked
onSave() => void(Unused if footer is controlled) Callback function to save at the end of the wizard, if not specified uses onClose
startAtStepnumber1The current step the wizard is on (1 or higher)
titlestringnullThe wizard title to display if header is desired
titleIdstringAn optional id for the title
widthnumber | stringnullCustom width of the wizard

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
ouiaSafeNo type infotrue
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
ouiaSafeNo type infotrue

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
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

WizardBody

*required
NameTypeDefaultDescription
activeSteprequiredWizardStepThe currently active WizardStep
aria-labelledbyrequiredstringAdds an accessible name to the wizard body by passing the the id of one or more elements. The aria-labelledby will only be applied when the body content overflows and renders a scrollbar.
childrenrequiredanyAnything that can be rendered in the Wizard body
aria-labelstringAdds an accessible name to the wizard body when the body content overflows and renders a scrollbar.
hasDrawerboolean
hasNoBodyPaddingbooleanfalseSet to true to remove the default body padding
isDrawerExpandedbooleanFlag indicating the wizard drawer is expanded
mainComponentReact.ElementType'div'Component used as the primary content container
onExpandDrawer() => voidCallback function for when the drawer is toggled

WizardFooter

*required
NameTypeDefaultDescription
childrenrequiredanyButtons in the footer

WizardToggle

*required
NameTypeDefaultDescription
activeSteprequiredWizardStepThe currently active WizardStep
isNavOpenrequiredbooleanIf the nav is open
navrequired(isWizardNavOpen: boolean) => React.ReactElementFunction that returns the WizardNav component
onNavTogglerequired(isOpen: boolean) => voidCallback function for when the nav is toggled
stepsrequiredWizardStep[]The wizard steps
aria-labelstring'Wizard Toggle'The button's aria-label
childrenReact.ReactNodeThe WizardFooter
hasDrawerbooleanFlag indicating the wizard has a drawer for at least one of the wizard steps
hasNoBodyPaddingbooleanfalseSet to true to remove body padding
isDrawerExpandedbooleanFlag indicating the wizard drawer is expanded
isInPagebooleantrueIf the wizard is in-page
mainAriaLabelstringnullAdds an accessible name to the wizard body when the body content overflows and renders a scrollbar.
mainAriaLabelledBystringnullAdds an accessible name to the wizard body by passing the the id of one or more elements. The aria-labelledby will only be applied when the body content overflows and renders a scrollbar.
onExpandDrawer() => voidCallback function for when the drawer is toggled

WizardStep

*required
NameTypeDefaultDescription
namerequiredReact.ReactNodeThe name of the step
canJumpTobooleanEnables or disables the step in the navigation. Enabled by default.
componentanyThe component to render in the main body
drawerPanelContentanyThe content to render in the drawer panel (use when hasDrawer prop is set on the wizard).
drawerToggleButtonReact.ReactNodeCustom drawer toggle button that opens the drawer.
enableNextboolean(Unused if footer is controlled) The condition needed to enable 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
idstring | numberOptional identifier
isDisabledbooleanFlag to disable the step in the navigation
isFinishedStepbooleanSetting to true hides the side nav and footer
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.
stepNavItemPropsReact.HTMLProps<HTMLButtonElement | HTMLAnchorElement> | WizardNavItemPropsProps to pass to the WizardNavItem
stepsWizardStep[]Sub steps

CSS variables

Expand or collapse columnSelectorVariableValue