Skip to main content
Kaleidoscope

StepCount

A step progress indicator that displays the current position within a multi-step flow, allowing users to navigate back to previous steps.

Default

A horizontal progress indicator showing numbered steps connected by lines. Previous steps are clickable, allowing users to navigate backwards through a flow.

Editable example
() => {
  const [step, setStep] = React.useState(0);
  const totalSteps = 4;

  return (
    <Stack gap="xl">
      <StepCount
        totalSteps={totalSteps}
        currentStep={step}
        goToAPreviousStep={setStep}
      />
      <Stack direction="horizontal" gap="s">
        <Button onClick={() => setStep((s) => Math.max(0, s - 1))} disabled={step === 0}>Previous</Button>
        <Button onClick={() => setStep((s) => Math.min(totalSteps - 1, s + 1))} disabled={step === totalSteps - 1}>Next</Button>
        <Button onClick={() => setStep(0)} disabled={step === 0}>Reset</Button>
      </Stack>
    </Stack>
  );
}

Best practices

  1. Use StepCount for linear, sequential flows where users benefit from seeing their progress (e.g. onboarding wizards, multi-step forms).
  2. Keep the total number of steps manageable — if a flow has more than 6-8 steps, consider grouping steps or simplifying the flow.
  3. Only allow navigation to previous steps, not future ones — users should complete each step before advancing.

Raised

Use the raised variant when the StepCount is placed on a surface where it needs more visual prominence.

Editable example
() => {
  const [step, setStep] = React.useState(2);
  const totalSteps = 4;

  return (
    <Stack gap="xl">
      <Card>
        <Stack padding="m">
          <StepCount
            totalSteps={totalSteps}
            currentStep={step}
            goToAPreviousStep={setStep}
            raised
          />
        </Stack>
      </Card>
      <Stack direction="horizontal" gap="s">
        <Button onClick={() => setStep((s) => Math.max(0, s - 1))} disabled={step === 0}>Previous</Button>
        <Button onClick={() => setStep((s) => Math.min(totalSteps - 1, s + 1))} disabled={step === totalSteps - 1}>Next</Button>
        <Button onClick={() => setStep(0)} disabled={step === 0}>Reset</Button>
      </Stack>
    </Stack>
  );
}

Navigating back

Clicking a previous step calls the goToAPreviousStep callback with that step's index. Only completed (previous) steps are clickable — the current and future steps are not interactive.

Editable example
() => {
  const [step, setStep] = React.useState(3);
  const totalSteps = 5;

  return (
    <Stack gap="xl">
      <StepCount
        totalSteps={totalSteps}
        currentStep={step}
        goToAPreviousStep={setStep}
      />
      <Stack direction="horizontal" gap="s">
        <Button onClick={() => setStep((s) => Math.max(0, s - 1))} disabled={step === 0}>Previous</Button>
        <Button onClick={() => setStep((s) => Math.min(totalSteps - 1, s + 1))} disabled={step === totalSteps - 1}>Next</Button>
        <Button onClick={() => setStep(0)} disabled={step === 0}>Reset</Button>
      </Stack>
    </Stack>
  );
}

Accessibility

  • This component currently uses plain div elements for clickable steps and lacks semantic markup, ARIA roles, and keyboard navigation. It should be updated in the future to use proper accessible patterns (e.g. a nav landmark, button elements for clickable steps, and aria-current="step").