Skip to main content Skip to docs navigation

Stepper

Create timelines, wizards, or step-by-step progress bars. Ideal for shopping carts, sign-up forms, and more.

GitHub Edit on GitHub
On this page

Examples

Stepper is built with CSS Grid and <ol> elements. By default, steps are displayed vertically. You can transform them into horizontal lists with responsive modifier classes.

Basic

Here's a simple example of a vertical stepper.

  1. Create account
  2. Confirm email
  3. Update profile
  4. Finish
HTML
<ol class="stepper">
  <li class="stepper-item active">Create account</li>
  <li class="stepper-item active">Confirm email</li>
  <li class="stepper-item">Update profile</li>
  <li class="stepper-item">Finish</li>
</ol>

Responsive

Steppers sometimes need to be responsive, so you can use the responsive modifier classes to change them from vertical to horizontal at different breakpoints. Responsive modifier classes are available for sm, md, lg, xl, and 2xl breakpoints.

  1. Create account
  2. Confirm email
  3. Update profile
  4. Finish
HTML
<ol class="stepper stepper-horizontal-md">
  <li class="stepper-item active">Create account</li>
  <li class="stepper-item active">Confirm email</li>
  <li class="stepper-item">Update profile</li>
  <li class="stepper-item">Finish</li>
</ol>

Gap

Customize the gap with styles that override the --bs-stepper-gap CSS variable.

  1. Create account
  2. Confirm email
  3. Update profile
  4. Finish
HTML
<ol class="stepper" style="--bs-stepper-gap: 3rem">
  <li class="stepper-item active">Create account</li>
  <li class="stepper-item active">Confirm email</li>
  <li class="stepper-item">Update profile</li>
  <li class="stepper-item">Finish</li>
</ol>

Variants

  1. Create account
  2. Confirm email
  3. Update profile
  4. Finish
HTML
<ol class="stepper stepper-horizontal">
  <li class="stepper-item active theme-accent">Create account</li>
  <li class="stepper-item">Confirm email</li>
  <li class="stepper-item active theme-success">Update profile</li>
  <li class="stepper-item active theme-danger">Finish</li>
</ol>

Overflow

Wrap your horizontal stepper in a .stepper-overflow container to enable horizontal scrolling when the stepper overflows its parent. Uses container-type: inline-size for container query support as opposed to a viewport-based media query.

  1. Create account
  2. Verify email address
  3. Complete profile setup
  4. Add payment method
  5. Review and confirm
  6. Finish onboarding
HTML
<div class="stepper-overflow">
  <ol class="stepper stepper-horizontal">
    <li class="stepper-item active">Create account</li>
    <li class="stepper-item active">Verify email address</li>
    <li class="stepper-item">Complete profile setup</li>
    <li class="stepper-item">Add payment method</li>
    <li class="stepper-item">Review and confirm</li>
    <li class="stepper-item">Finish onboarding</li>
  </ol>
</div>

Playground

Experiment with stepper options including orientation, breakpoints, step count, and more.
  1. Create account
  2. Confirm email
  3. Update profile
  4. Finish
HTML
<ol class="stepper">
  <li class="stepper-item active">Create account</li>
  <li class="stepper-item active">Confirm email</li>
  <li class="stepper-item">Update profile</li>
  <li class="stepper-item">Finish</li>
</ol>

Alignment

Use text alignment utilities (because we use display: inline-grid) to align the steps. The inline grid arrangement allows us to keep the steps equal width and ensures the connecting lines are rendered correctly.

  1. Default stepper
  2. Confirm email
  3. Update profile
  4. Finish
HTML
<ol class="stepper stepper-horizontal">
  <li class="stepper-item active">Default stepper</li>
  <li class="stepper-item active">Confirm email</li>
  <li class="stepper-item">Update profile</li>
  <li class="stepper-item">Finish</li>
</ol>
  1. Center stepper
  2. Confirm email
  3. Update profile
  4. Finish
HTML
<ol class="stepper stepper-horizontal">
  <li class="stepper-item active">Center stepper</li>
  <li class="stepper-item active">Confirm email</li>
  <li class="stepper-item">Update profile</li>
  <li class="stepper-item">Finish</li>
</ol>
  1. End stepper
  2. Confirm email
  3. Update profile
  4. Finish
HTML
<ol class="stepper stepper-horizontal">
  <li class="stepper-item active">End stepper</li>
  <li class="stepper-item active">Confirm email</li>
  <li class="stepper-item">Update profile</li>
  <li class="stepper-item">Finish</li>
</ol>

Apply .w-100 to the stepper to make it full width. Stepper items will be stretched to fill the available space. Alignment doesn't affect full-width steppers.

  1. Create account
  2. Confirm email
  3. Update profile
  4. Finish
HTML
<ol class="stepper stepper-horizontal w-100">
  <li class="stepper-item active">Create account</li>
  <li class="stepper-item active">Confirm email</li>
  <li class="stepper-item">Update profile</li>
  <li class="stepper-item">Finish</li>
</ol>

With anchors

Use anchor elements to build your stepper if it links across multiple pages. Add role="button" or use <button> elements if you're linking across sections in the same document.

Consider using our link utilities for quick color control.

Create account Confirm email Update profile Finish
HTML
<div class="stepper">
  <a href="#" role="button" class="stepper-item link-body-emphasis active">Create account</a>
  <a href="#" role="button" class="stepper-item link-body-emphasis active">Confirm email</a>
  <a href="#" role="button" class="stepper-item link-secondary">Update profile</a>
  <a href="#" role="button" class="stepper-item link-secondary">Finish</a>
</div>

CSS

Variables

Steppers use CSS variables for easier customization.

SCSS
--stepper-size: #{$stepper-size};
--stepper-gap: #{$stepper-gap};
--stepper-bg: #{$stepper-bg};
--stepper-track-size: #{$stepper-track-size};
--stepper-active-color: #{$stepper-active-fg};
--stepper-active-bg: #{$stepper-active-bg};

Sass variables

SCSS
$stepper-size: 2rem;
$stepper-gap: 1rem;
$stepper-track-size: .25rem;
$stepper-bg: var(--bg-2);
$stepper-active-fg: var(--primary-contrast);
$stepper-active-bg: var(--primary-bg);
// $stepper-vertical-gap: .5rem;

Sass mixin

SCSS
@mixin stepper-horizontal() {
  display: inline-grid;
  grid-auto-columns: 1fr;
  grid-auto-flow: column;

  .stepper-item {
    grid-template-rows: repeat(2, var(--stepper-size));
    grid-template-columns: auto;
    justify-items: center;

    &::after {
      top: calc((var(--stepper-size) * .5) - (var(--stepper-track-size) * .5));
      right: 0;
      bottom: auto;
      left: calc(-50% - var(--stepper-gap));
      width: auto;
      height: var(--stepper-track-size);
    }

    &:last-child::after {
      right: 50%;
    }
  }
}

Overflow wrapper

SCSS
.stepper-overflow {
  container-type: inline-size;
  overflow-x: auto;
  overscroll-behavior-x: contain;
  -webkit-overflow-scrolling: touch;

  > .stepper {
    width: max-content;
    min-width: 100%;
  }
}