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.
- Create account
- Confirm email
- Update profile
- 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.
- Create account
- Confirm email
- Update profile
- 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.
- Create account
- Confirm email
- Update profile
- 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
Create account
- Confirm email
Update profile
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.
- Create account
- Verify email address
- Complete profile setup
- Add payment method
- Review and confirm
- 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.
- CreateCreate an account.
- ConfirmConfirm your email.
- Set-upConfigure your profile.
- FinishWelcome 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.
- Create accountComplete
- Confirm emailComplete
- Update profileIn-progress
- FinishPending
<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.
- Default stepper
- Confirm email
- Update profile
- 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>- Center stepper
- Confirm email
- Update profile
- 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>- End stepper
- Confirm email
- Update profile
- 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.
- Create account
- Confirm email
- Update profile
- 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 variable | Default |
|---|---|
--bs-stepper-size | 2rem |
--bs-stepper-gap | 1rem |
--bs-stepper-font-size | var(--bs-font-size-sm) |
--bs-stepper-text-gap | 0.5rem |
--bs-stepper-track-size | 0.125rem |
--bs-stepper-bg | var(--bs-bg-2) |
--bs-stepper-active-color | var(--bs-primary-contrast) |
--bs-stepper-active-bg | var(--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.