grommet
docs
components

New! Wizard is in beta, the API is subject to change. Feel free to test it out and let us know what you think!

Wizard

a multi-step form component

GitHub

Props

aria-label

Accessibility label for the wizard component.

string
"Onboarding"

children

Additional content to render inside the wizard.

node | element
<Text>Additional wizard content</Text>

currentStep

The id of the currently active step.

string
"profile"

defaultStep

The id of the initial step to display when the wizard loads.

string
"account"

defaultValue

Initial form values for all steps in the wizard. This is of type TValue which defaults to Record<string, any>.

object
{ email: '', name: '' }

id

Unique identifier for the wizard instance.

string
"signup-wizard"

messages

Custom messages for wizard labels and buttons.

object
{
  previous: "Previous",
  next: "Next",
  skip: "Skip",
  cancel: "Cancel",
  close: "Close",
  complete: "Complete",
  stepHeader: {
    counter: "Step {step} of {total}"
  },
  progress: "Wizard progress",
  validationError: "Please complete required fields."
}

onCancel

Callback function triggered when the wizard is cancelled. Receives an event object containing the current form value and the reason for cancellation.

function
(event: { value: { name: "Alice", active: true }, reason: 'user' }) => handleCancel(event.value)

onChange

Callback function triggered when form values change in any step. Receives an event object containing the updated form value.

function
(event: { value: { name: "Alice", active: true } }) => setFormData(event.value)

onComplete

Callback function triggered when the wizard is completed successfully. Receives an event object containing the final form value and an array of completed step IDs.

function
(event: { value: { name: "Alice", active: true }, completedSteps: string[] }) => submitForm(event.value)

onStepChange

Callback function triggered when the active step changes. Receives a StepChangeEvent object with step change details.

function
(event: StepChangeEvent) => console.log('Step changed:', event.stepId)

renderStep

Custom function to render step content instead of using the step's render property. Receives the current step and the wizard context API.

function
(step: WizardStep, api: WizardContextValue) => <Box>{step.title}</Box>

scrollToTop

Whether to scroll to the top of the page when the step changes.

boolean
true
false

showProgress

Display style for the progress indicator showing the wizard steps.

string
'horizontal'
'vertical'

steps

Array of WizardStep objects defining each step in the wizard. Each step includes id, title, description, and render function.

array
[{ id: 'account', title: 'Account', description: 'Account info', render: () => null }]

title

The main title displayed at the top of the wizard.

string
"Set up your account"

value

Current form values for the wizard. Use this to control the wizard's form state.

object
{ email: 'user@example.com', name: 'John Doe' }

Theme

wizard.container.gap

The gap between wizard container sections.

string
"none"

wizard.container.background

The background color of the wizard container.

string
"background-back"

wizard.body.pad

The padding for the wizard body area.

string
"large"
object
{ horizontal: "large", vertical: "large" }

wizard.body.gap

The gap between elements in the wizard body.

string
"medium"
object
{ row: "none", column: "medium" }

wizard.header.pad

The padding for the wizard header.

string
"medium"
object
{ horizontal: "large", vertical: "small" }

wizard.header.background

The background color of the wizard header.

string
"background-front"

wizard.header.title.size

The font size of the wizard title.

string
"small"

wizard.header.close.icon

The icon to use for the close button.

element
FormClose

wizard.progress.horizontal.pad

The padding for the horizontal progress indicator.

string
"medium"
object
{ horizontal: "none", vertical: "none" }

wizard.progress.vertical.width

The width of the vertical progress indicator.

string
"small"

wizard.progress.vertical.pad

The padding for the vertical progress indicator.

string
"medium"
object
undefined

wizard.stepHeader.pad

The padding for the step header.

string
"medium"
object
{ horizontal: "none", vertical: "none" }

wizard.stepHeader.gap

The gap between step header elements.

string
"medium"

wizard.stepHeader.counter.size

The font size of the step counter.

string
"small"

wizard.stepHeader.counter.color

The color of the step counter text.

string
"text"

wizard.stepHeader.title.size

The font size of the step title.

string
"large"

wizard.stepHeader.title.margin

The margin for the step title.

string
"none"
object
{ top: "small", bottom: "small" }

wizard.stepHeader.description.size

The font size of the step description.

string
"medium"

wizard.stepHeader.description.color

The color of the step description text.

string
"text-weak"

wizard.stepHeader.description.margin

The margin for the step description.

string
"small"
object
{ top: "xsmall", bottom: "none" }

wizard.content.pad

The padding for the step content area.

string
"medium"
object
{ vertical: "large", horizontal: "large" }

wizard.content.gap

The gap between elements in the step content.

string
"medium"

wizard.content.background

The background color of the step content area.

string
"background-front"

wizard.content.round

The border radius for the step content.

string
"small"

wizard.content.margin

The margin for the step content area.

string
"small"
object
{ top: "medium" }

wizard.footer.background

The background color of the wizard footer.

string
"background-front"

wizard.footer.border

The border style for the wizard footer.

string
"top"
object
{
  side: "top" | "bottom" | "left" | "right",
  color: "...",
  size: "..."
}

wizard.footer.gap

The gap between footer elements.

string
"medium"
object
{ row: "xsmall", column: "small" }

wizard.footer.pad

The padding for the wizard footer.

string
"medium"
object
{ horizontal: "large", vertical: "small" }

wizard.footer.justify

How to justify footer button content.

string
"end"

wizard.footer.button.next.icon

The icon for the next button.

element
"FormNext"

wizard.footer.button.previous.icon

The icon for the previous button.

element
"FormPrevious"

wizard.footer.button.complete.icon

The icon for the complete button.

element
undefined

wizard.footer.button.skip.icon

The icon for the skip button.

element
"FormNext"

wizard.footer.button.cancel.icon

The icon for the cancel button.

element
undefined