Loading...
Skip to main content

Stepper

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

Use Stepper and StepperItem for ordered steps, StepperNav and StepperLink for navigation, and StepperOverflow for scrollable horizontal steps. The horizontal prop accepts true or a breakpoint such as "sm"; items accept active and theme.

Examples

Stepper renders an ordered list and uses CSS Grid for layout. Steps are vertical by default; set its horizontal prop to a breakpoint to switch to a horizontal layout responsively.

Basic

Here’s a simple example of a vertical stepper.

  1. Create account
  2. Confirm email
  3. Update profile
  4. Finish
<div className="d-block overflow-auto">
<Stepper>
<StepperItem active>
Create account
</StepperItem>
<StepperItem active>
Confirm email
</StepperItem>
<StepperItem>
Update profile
</StepperItem>
<StepperItem>
Finish
</StepperItem>
</Stepper>
</div>

Responsive

For container-query-based horizontal layouts, place Stepper inside a parent with the contains-inline utility applied through className, then set the horizontal prop to the desired breakpoint.

  1. Create account
  2. Confirm email
  3. Update profile
  4. Finish
<div
className="d-block overflow-auto p-2"
style={{
maxWidth: '100%',
resize: 'horizontal'
}}
>
<div className="contains-inline">
<Stepper horizontal="sm">
<StepperItem active>
Create account
</StepperItem>
<StepperItem active>
Confirm email
</StepperItem>
<StepperItem>
Update profile
</StepperItem>
<StepperItem>
Finish
</StepperItem>
</Stepper>
</div>
</div>

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
<div className="d-block overflow-auto">
<Stepper
style={{
'--bs-stepper-gap': '3rem'
}}
>
<StepperItem active>
Create account
</StepperItem>
<StepperItem active>
Confirm email
</StepperItem>
<StepperItem>
Update profile
</StepperItem>
<StepperItem>
Finish
</StepperItem>
</Stepper>
</div>

Variants

  1. Create account

  2. Confirm email
  3. Update profile

  4. Finish

<div className="d-block overflow-auto">
<Stepper horizontal>
<StepperItem
active
theme="accent"
>
<p>
Create account
</p>
</StepperItem>
<StepperItem>
Confirm email
</StepperItem>
<StepperItem
active
theme="success"
>
<p>
Update profile
</p>
</StepperItem>
<StepperItem
active
theme="danger"
>
<p>
Finish
</p>
</StepperItem>
</Stepper>
</div>

Overflow

Wrap a horizontal stepper in StepperOverflow to enable horizontal scrolling when it exceeds its parent. It uses container-type: inline-size to support container queries.

  1. Create account
  2. Verify email address
  3. Complete profile setup
  4. Add payment method
  5. Review and confirm
  6. Finish onboarding
<div className="d-block overflow-auto">
<StepperOverflow>
<Stepper horizontal>
<StepperItem active>
Create account
</StepperItem>
<StepperItem active>
Verify email address
</StepperItem>
<StepperItem>
Complete profile setup
</StepperItem>
<StepperItem>
Add payment method
</StepperItem>
<StepperItem>
Review and confirm
</StepperItem>
<StepperItem>
Finish onboarding
</StepperItem>
</Stepper>
</StepperOverflow>
</div>

Complex

Add additional content beyond labels to provide more context within each step, such as descriptions, helper messages, status indicators, or other decorative elements.

  1. Create
    Create an account.
  2. Confirm
    Confirm your email.
  3. Set-up
    Configure your profile.
  4. Finish
    Welcome aboard!
<div className="d-block overflow-auto">
<Stepper>
<StepperItem
active
className="align-items-start"
>
<div className="pt-1">
<div className="fw-semibold">
Create
</div>
<small className="fg-3">
Create an account.
</small>
</div>
</StepperItem>
<StepperItem
active
className="align-items-start"
>
<div className="pt-1">
<div className="fw-semibold">
Confirm
</div>
<small className="fg-3">
Confirm your email.
</small>
</div>
</StepperItem>
<StepperItem className="align-items-start">
<div className="pt-1">
<div className="fw-semibold">
Set-up
</div>
<small className="fg-3">
Configure your profile.
</small>
</div>
</StepperItem>
<StepperItem className="align-items-start">
<div className="pt-1">
<div className="fw-semibold">
Finish
</div>
<small className="fg-3">
Welcome aboard!
</small>
</div>
</StepperItem>
</Stepper>
</div>

Mix with other components, like badges, and our theme helpers to create a more unique steppers.

  1. Create account
    Complete
  2. Confirm email
    Complete
  3. Update profile
    In-progress
  4. Finish
    Pending
<div className="d-block overflow-auto">
<Stepper
className="w-100"
horizontal
>
<StepperItem
active
theme="success"
>
<div>
<div>
Create account
</div>
<Badge variant="subtle">
Complete
</Badge>
</div>
</StepperItem>
<StepperItem
active
theme="success"
>
<div>
<div>
Confirm email
</div>
<Badge variant="subtle">
Complete
</Badge>
</div>
</StepperItem>
<StepperItem
active
theme="primary"
>
<div>
<div>
Update profile
</div>
<Badge variant="subtle">
In-progress
</Badge>
</div>
</StepperItem>
<StepperItem theme="secondary">
<div>
<div>
Finish
</div>
<Badge variant="subtle">
Pending
</Badge>
</div>
</StepperItem>
</Stepper>
</div>

Alignment

Use text alignment utilities on the wrapper around Stepper (which uses display: inline-grid) to align the steps. The inline grid arrangement keeps steps equal width and ensures connecting lines are rendered correctly.

  1. Default stepper
  2. Confirm email
  3. Update profile
  4. Finish
<div className="d-block overflow-auto">
<Stepper horizontal>
<StepperItem active>
Default stepper
</StepperItem>
<StepperItem active>
Confirm email
</StepperItem>
<StepperItem>
Update profile
</StepperItem>
<StepperItem>
Finish
</StepperItem>
</Stepper>
</div>
  1. Center stepper
  2. Confirm email
  3. Update profile
  4. Finish
<div className="text-center overflow-auto">
<Stepper horizontal>
<StepperItem active>
Center stepper
</StepperItem>
<StepperItem active>
Confirm email
</StepperItem>
<StepperItem>
Update profile
</StepperItem>
<StepperItem>
Finish
</StepperItem>
</Stepper>
</div>
  1. End stepper
  2. Confirm email
  3. Update profile
  4. Finish
<div className="text-end overflow-auto">
<Stepper horizontal>
<StepperItem active>
End stepper
</StepperItem>
<StepperItem active>
Confirm email
</StepperItem>
<StepperItem>
Update profile
</StepperItem>
<StepperItem>
Finish
</StepperItem>
</Stepper>
</div>

Apply a full-width utility through Stepper's className to make it span the available width. Step items will stretch to fill the space; alignment does not affect full-width steppers.

  1. Create account
  2. Confirm email
  3. Update profile
  4. Finish
<div className="d-block overflow-auto">
<Stepper
className="w-100"
horizontal
>
<StepperItem active>
Create account
</StepperItem>
<StepperItem active>
Confirm email
</StepperItem>
<StepperItem>
Update profile
</StepperItem>
<StepperItem>
Finish
</StepperItem>
</Stepper>
</div>

With anchors

Use StepperLink for steps that navigate between pages. Use StepperButton for steps that trigger an action within the current page.

Use link utilities through StepperLink's className for quick color control.

<div className="d-block overflow-auto">
<StepperNav>
<StepperLink
active
href="#"
role="button"
>
Create account
</StepperLink>
<StepperLink
active
href="#"
role="button"
>
Confirm email
</StepperLink>
<StepperLink
href="#"
role="button"
theme="secondary"
>
Update profile
</StepperLink>
<StepperLink
href="#"
role="button"
theme="secondary"
>
Finish
</StepperLink>
</StepperNav>
</div>

CSS

Variables

Customize the component with the following local CSS variables. Override them through the wrapper’s style prop or your own CSS module.

CSS variableDefault
--bs-stepper-size2rem
--bs-stepper-gap1rem
--bs-stepper-font-sizevar(--bs-font-size-sm)
--bs-stepper-text-gap0.5rem
--bs-stepper-track-size0.125rem
--bs-stepper-bgvar(--bs-bg-2)
--bs-stepper-active-colorvar(--bs-primary-contrast)
--bs-stepper-active-bgvar(--bs-primary-bg)

Overflow wrapper

The StepperOverflow wrapper establishes an inline-size query container with horizontal scrolling. The horizontal stepper retains its minimum content width, keeping labels readable when the available space is narrow.

Documentation navigation
On this page
On this page