Stepper

Stepper exports multiple components that combine to create a stepped progress view.

Stepper.StepBack represents the backwards navigation element. It can receive either a child text node or a label prop as a function that receives activeStep as an argument in order to possibly render different labels based on the current step the user is on. It is automatically disabled while the user is viewing the first step.

Stepper.StepForward represents the forward navigation element. It can receive either a child text node or a label prop as a function that receives activeStep as an argument in order to possibly render different labels based on the current step the user is on. It can receive an onClick prop to override its default behaviour in case some logic or validation needs to be applied before going to the next step.

Stepper.Steps holds the actual bullet list. It can receive a css prop, allowing for full customization.

The root Stepper component must be passed stepCount as a number in order to display the desired number of bullet steps. It also takes onStepChange as a function that takes activeStep as an argument. This can be used to determine what content to display, based on the current step. It can also take onComplete as a function that gets called when the user clicks the StepForward button while on the last step.

<Stepper
  stepCount={3}
  css={{ display: 'grid', gridTemplateColumns: '1fr auto 1fr' }}
>
  <Stepper.StepBack>Back</Stepper.StepBack>
  <Stepper.Steps />
  <Stepper.StepForward>Next</Stepper.StepForward>
</Stepper>

The root Stepper component can also take an allowSkip prop that allows the user to navigate by clicking the actual bullets. However, navigating by clicking a bullet is only possible if the user has already viewed it by using the Next button.

Below is a more complex example that shows how to dynamically render the button labels, get the activeStep in order to potentially use it to determine what content to render based on the current position, and use an onComplete function to trigger custom behaviour when the user reaches the final step.

<Stepper
  stepCount={3}
  allowSkip
  onComplete={() => console.log('Finished')}
  onStepChange={(activeStep) =>
    console.log('Do something with the active step')
  }
  css={{ display: 'grid', gridTemplateColumns: '1fr auto 1fr' }}
>
  <Stepper.StepBack label={(activeStep) => 'Back'} />
  <Stepper.Steps />
  <Stepper.StepForward
    label={(activeStep) => (activeStep === 2 ? 'Finish' : 'Next')}
  />
</Stepper>

Below is how to override the forward default behavior if some logic or validation need to be done before moving to the next step

<Stepper
  stepCount={3}
  css={{ display: 'grid', gridTemplateColumns: '1fr auto 1fr' }}
>
  <Stepper.StepBack>Back</Stepper.StepBack>
  <Stepper.Steps />
  <Stepper.StepForward
    onClick={(goToNextStep) => {
      // do something before
      goToNextStep()
    }}
  >
    Next
  </Stepper.StepForward>
</Stepper>

The root Stepper component also allows the user to pass a steps prop in order to render step labels. When the steps prop is passed, the Stepper component will be used as a controlled component thereby taking control of its state. When used as a controlled component, navigation across steps, and identifying the state of a step would be controlled by the array of steps passed to the component.

Below is an example that shows how to use the controlled component. Each object in the steps array must include a label and a status property to determine what content to render based on the current position.

<Stepper
  steps={[
    {
      label: 'Step 1',
      status: 'viewed'
    },
    {
      label: 'Step 2',
      status: 'active'
    },
    {
      label: 'Step 3',
      status: 'default'
    }
  ]}
>
  <Stepper.Steps />
</Stepper>

The root Stepper component also allows the user to pass a hideLabels prop in order to hide step labels passed in the step object.

Below is an example that shows how to hide step labels

<Stepper
  steps={[
    {
      label: 'Step 1',
      status: 'viewed'
    },
    {
      label: 'Step 2',
      status: 'active'
    },
    {
      label: 'Step 3',
      status: 'default'
    }
  ]}
  hideLabels={true}
>
  <Stepper.Steps />
</Stepper>

The root Stepper component also allows the user to pass a showCompletedIcons prop in order to replace step numbers with tick icons when the step has been completed. This defaults to false.

<Stepper
  steps={[
    {
      label: 'Step 1',
      status: 'completed'
    },
    {
      label: 'Step 2',
      status: 'active'
    },
    {
      label: 'Step 3',
      status: 'default'
    }
  ]}
  showCompletedIcons
>
  <Stepper.Steps />
</Stepper>

The root Stepper component also allows the user to pass a direction prop in order to the alternate the component direction .

Below is an example that shows how to render steps in vertical direction.

<Stepper stepCount={2} direction="vertical">
  <Stepper.Steps />
</Stepper>