How do you create a Bootstrap progress bar?
Load the stylesheet, add a wrapper, nest the bar inside it. In Bootstrap 5.3 that’s most of the job.
- Load the Bootstrap stylesheet (5.3.8 is the current release as of October 2026).
- Add a
div with class progress, plus role="progressbar", an aria-label and the three value attributes. - Nest a
div with class progress-bar inside it. - Set the width on that inner bar and mirror the same value in
aria-valuenow.
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB" crossorigin="anonymous">
<div class="progress" role="progressbar" aria-label="Upload progress" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar" style="width: 25%"></div>
</div>
According to the Bootstrap docs, the wrapper defines the maximum value of the track, while the inner bar draws the fill and can hold a label.
No script is involved in drawing it. Both classes ship in the compiled stylesheet of the Bootstrap framework, and CSS alone draws the fill.
The skipped native element was a deliberate call. Two plain HTML elements and a few attributes are all the component needs (Bootstrap docs).
Setting the value: width and ARIA attributes
A progress bar carries its value twice. The width on .progress-bar draws the fill, and aria-valuenow on .progress is what a screen reader announces.
Nothing links the two. The 5.3.8 stylesheet source never reads aria-valuenow, so you set both yourself.
Setting the width with inline style or utilities
Inline style accepts any percentage, for example width: 37.5%. The utilities are narrower. Bootstrap’s sizing docs list .w-25, .w-50, .w-75, .w-100 and .w-auto, and nothing in between. Custom CSS works too, which is handy when the value comes from a stylesheet variable.
The 5.3.8 source sets no width on a standalone .progress-bar. A bar with none collapses to the width of its label, or to nothing when it has no label.
The wrapper marks 100% of the track, so width equals value divided by maximum. Say 30 of 80 files have uploaded. The inline width comes out at 37.5%, with aria-valuenow at 30 and aria-valuemax at 80.
Required ARIA attributes in Bootstrap 5.3
Since v5.3.0, role="progressbar" and the value attributes sit on the .progress wrapper, not on the inner bar.
The reason was screen reader behavior. With the ARIA attributes on the inner element, some readers skipped zero-value bars (Bootstrap migration guide).
The wrapper takes the role="progressbar" attribute along with aria-valuenow for the current value, aria-valuemin (usually 0) and aria-valuemax (usually 100). It also needs an accessible name, which comes from aria-label or aria-labelledby.
Skip the name and two bars on the same page sound identical. Give each its own, such as “Upload progress” and “Video conversion”.
The legacy structure keeps working until v6, according to the Bootstrap docs, so old markup does not break inside version 5.
How to change progress bar height, label and color
Height goes on .progress. The label sits inside .progress-bar, and color comes from bg-* or text-bg-* classes. Mixing up which element gets what is the usual mistake.
Height
Set height on the wrapper only. The inner bar resizes with it, and the default is 1rem (Bootstrap docs, v5.3.8).
<div class="progress" role="progressbar" aria-label="Disk usage" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100" style="height: 20px">
<div class="progress-bar" style="width: 25%"></div>
</div>
The label font is 0.75 times the base size and the wrapper hides overflow. A 1px hairline bar cannot show text at all.
Labels
Put the text between the .progress-bar tags. The bar centers its content and keeps it on one line (white-space: nowrap in the 5.3.8 source).
Overflow is hidden by default, so a label longer than the fill gets cut off. Adding .overflow-visible lets the text spill out, but then it has to pass contrast against the track and the fill both.
Early in a task the fill is narrow, so an in-bar label is the first thing to break. The Bootstrap docs recommend placing the label outside the bar when text can overlap the fill. I’d do that by default.
Colors
bg-* classes color the fill. text-bg-* colors the fill and picks a matching text color in one class.
| Class | What it sets | Use it when |
|---|
bg-success, bg-info, bg-warning, bg-danger | Fill color only | The bar has no label |
text-bg-success and siblings | Fill plus contrasting text color | The label sits inside the bar |
Custom class with a text-* utility | Your own color pair | Brand colors outside the theme |
The text-bg-* helpers arrived in v5.2.0 and pair each background with a contrasting text color (migration guide). Bootstrap had already raised its contrast ratio from 3:1 to 4.5:1 in v5.0.0.
Custom pairs get no such check. A label on a brand color needs enough color contrast against both the fill and the gray track.
That sounds like a small detail until you look at the numbers. WebAIM’s 2026 Million report found low-contrast text on 83.9% of home pages, the most common failure it detected.
Color also carries no meaning for screen reader users. Put the status in visible text, or in .visually-hidden text, as the docs advise.
Striped and animated progress bars
Stripes come from .progress-bar-striped and motion from .progress-bar-animated. Both go on the inner .progress-bar element.
The stripes are a CSS gradient laid over the bar color, and the gradient’s tile size reads --bs-progress-height. Set the height through that variable on a striped bar, because a plain height on the wrapper leaves the stripe tile at 1rem.
<div class="progress" role="progressbar" aria-label="Importing data" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100" style="--bs-progress-height: 20px">
<div class="progress-bar progress-bar-striped progress-bar-animated" style="width: 75%"></div>
</div>
The motion comes from a CSS keyframes animation named progress-bar-stripes. It runs at 1s, linear, infinite, and shifts the gradient’s horizontal background position (5.3.8 source).
Because the animation moves the stripe gradient, .progress-bar-animated only shows when .progress-bar-striped sits on the same element.
The 5.3.8 source also has two Sass switches. With $enable-transitions set to false, the keyframes and the animated class are not compiled at all. $enable-reduced-motion, when true, applies animation: none inside a prefers-reduced-motion: reduce media query, so the stripes stay still.
The Bootstrap progress docs page does not mention the reduced-motion rule. You only find it in the source, in scss/_progress.scss.
A misspelling circulates in tutorials: progress-bar-stripped. The 5.3.8 source has no rule for it, so the bar renders as a plain fill.
Reserve animated stripes for a task that is still running. On a bar at 100%, moving stripes suggest work that has already finished.
How do you stack multiple bars in one progress bar?
Stacking takes a .progress-stacked container around several .progress elements. Each segment’s width goes on its own .progress, not on the inner bar.
<div class="progress-stacked">
<div class="progress" role="progressbar" aria-label="Documents" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100" style="width: 20%">
<div class="progress-bar"></div>
</div>
<div class="progress" role="progressbar" aria-label="Photos" aria-valuenow="35" aria-valuemin="0" aria-valuemax="100" style="width: 35%">
<div class="progress-bar bg-success"></div>
</div>
<div class="progress" role="progressbar" aria-label="Backups" aria-valuenow="15" aria-valuemin="0" aria-valuemax="100" style="width: 15%">
<div class="progress-bar bg-info"></div>
</div>
</div>
Each segment is a progress bar in its own right, with its own role, value attributes and accessible name. Its aria-valuenow matches its own width rather than a running total (the docs example uses 15, 30 and 20).
The 5.3.8 source explains the width rule. Inside the container, every inner bar is forced to width: 100% of its segment, so the segment’s width is the only one that counts.
Stacked bars tend to break in predictable ways. Segments that add up past 100% get the last one clipped, because the container hides overflow. One shared aria-label on every segment leaves screen reader users unable to tell them apart. And a width on the inner .progress-bar gets ignored, since the docs call for it on the segment.
Before 5.3, the docs stacked bars by putting several .progress-bar elements inside one .progress, and the 4.6 and 5.2 docs both show it. Some tutorials also use “stacked” for separate bars placed in rows, which is a different layout.
Updating a Bootstrap progress bar with JavaScript
Bootstrap ships no script for this, so one small function has to update the width and the ARIA value together. The progress docs have no JavaScript section, and the 5.3.8 stylesheet draws the whole component, which leaves a few lines of plain JavaScript.
function setProgress(wrapper, value, max = 100) {
const bar = wrapper.querySelector('.progress-bar');
const percent = (value / max) * 100;
wrapper.setAttribute('aria-valuenow', value);
wrapper.setAttribute('aria-valuemax', max);
bar.style.width = percent + '%';
if (value >= max) {
bar.classList.remove('progress-bar-animated');
}
}
The third argument covers bars whose maximum is not 100. At completion the function also strips the animated class, so a finished bar stops moving.
The bar ships with a width transition (width .6s ease, set by $progress-bar-transition), so each update glides in with no extra code.
Strict CSP is the other case to know about. If a Content Security Policy blocks inline styles, a style attribute in the markup is ignored. Setting element.style.width from script still works, which is the workaround the Bootstrap 3.4.1 docs describe, and the .w-* utilities are unaffected because they live in the stylesheet.
Customizing the Bootstrap progress bar with Sass and CSS variables
To restyle one bar, override a CSS variable on its .progress. To restyle every bar in the project, change the Sass variables before compiling. CSS variables on the component arrived in v5.2.0 (Bootstrap docs).
<div class="progress" role="progressbar" aria-label="Storage used" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="--bs-progress-bar-bg: #6f42c1; --bs-progress-border-radius: 50rem">
<div class="progress-bar" style="width: 60%"></div>
</div>
Two variables produce a pill-shaped purple bar. Add a bg-* class to the inner bar and the class wins, because utilities are !important by default ($enable-important-utilities is true in 5.3.8).
The documented defaults in Bootstrap 5.3.8 start with a track background of var(--bs-secondary-bg), so it follows the active color mode, and a bar background of $primary, which is #0d6efd. Bar text is $white. The corner radius is var(--bs-border-radius), .375rem out of the box, and the inset shadow is var(--bs-box-shadow-inset).
Sass overrides must sit after the functions import and before the variables import. Once a default variable has been used, it cannot be changed, so a late override does nothing (Bootstrap migration guide).
Stacked bars need the variable on each segment. Every .progress declares the variables itself, so a value set on .progress-stacked never reaches the segments.
Overrides for the rest of the framework follow the same cascade rules, which the guide to overriding Bootstrap CSS walks through.
Which progress bar markup should you use?
For new work, use the Bootstrap 5.3 structure. Older markup only makes sense where a framework upgrade is not planned. And when the task has no measurable end, the native HTML progress element is the better pick.
Bootstrap 3, 4 and 5.3 markup compared
The official Bootstrap 3 and Bootstrap 4 docs both carry an end-of-life banner, and Bootstrap 5.0.0 dropped Internet Explorer 10 and 11 (migration guide). A project that must still serve those browsers stays on an unsupported release.
| Aspect | Bootstrap 3.4.1 | Bootstrap 4.6 | Bootstrap 5.3 |
|---|
| ARIA attributes | Inner .progress-bar | Inner .progress-bar | .progress wrapper |
| Color classes | progress-bar-success, -info, -warning, -danger | bg-success and siblings | bg-* or text-bg-* |
| Animated stripes | .active on a striped bar | .progress-bar-animated | .progress-bar-animated |
| Stacked bars | Several bars in one .progress | Several bars in one .progress | .progress-stacked around segments |
| Hidden label text | .sr-only | .sr-only | .visually-hidden |
Tutorials mix the generations freely. Some Bootstrap 4 guides tell readers to color bars with background classes, while others still demonstrate progress-bar-success, a Bootstrap 3 class.
Every cell above comes from the official 3.4.1, 4.6 and 5.3 docs, which is the safest place to settle a disagreement.
Bootstrap progress bar versus the HTML progress element
| Criterion | Bootstrap progress bar | HTML progress element |
|---|
| Accessibility role | Added with role="progressbar" on .progress | Implicit progressbar role (MDN) |
| Unknown duration | No indeterminate state in the 5.3 docs | Omit the value attribute (MDN) |
| Segments | .progress-stacked | One value only |
| Text on the bar | Label inside .progress-bar | Text between the tags is a fallback, not a label (MDN) |
| Styling hooks | Classes and --bs-progress-* variables | Vendor pseudo-elements such as ::-webkit-progress-bar |
Inside a Bootstrap project, the Bootstrap bar handles anything measured and the native element handles open-ended waits. A page that loads Bootstrap for nothing else can skip the framework and use a hand-built CSS progress bar.
Support is no reason to avoid the native element, which has been available across browsers since July 2015 (MDN). Its look varies by engine, which is why MDN lists separate ::-webkit- and ::-moz- pseudo-elements.
Bootstrap Progress Bar FAQ
Can you make a vertical Bootstrap progress bar?
Not out of the box. The 5.3 docs describe only horizontal bars, with the fill sized by width.
A vertical version needs custom CSS: a tall, narrow wrapper, a column flex direction, and a fill sized by height. The built-in transition targets width only, so you have to add your own height transition.
How do you show file upload progress with a progress bar?
Call the setProgress function from whatever event reports bytes sent. Pass bytes sent as the value and total bytes as the maximum.
The function computes the percentage itself. When the total size is unknown, no percentage exists, and the native HTML progress element without a value attribute fits better.
Which values should a multi-step form progress bar use?
The current step is the value and the number of steps is the maximum. On step 3 of 5, aria-valuenow is 3, aria-valuemax is 5 and the width is 60%.
Show “Step 3 of 5” as text beside the bar. Labels inside a narrow fill get clipped.
Is a spinner better than a progress bar for loading states?
Yes, when completion cannot be measured. The progress component expects a known value, and spinners are a separate component built for open-ended waits.
Under reduced motion, spinners slow down (Bootstrap v5.0.0 migration guide), while animated stripes stop entirely (5.3.8 source).
Testing a Bootstrap Progress Bar With a Screen Reader
A finished Bootstrap progress bar passes when a screen reader announces its accessible name and current value at 0 and 100, plus somewhere in the middle.
Start by inspecting the .progress wrapper for the role, the value attributes and a name. That takes seconds and rules out missing attributes before any listening starts. Then listen at 0, 50 and 100 percent, and repeat after every scripted update.
The scripted pass comes last for a reason. Only a live update shows whether the ARIA value moved with the width.
The cost is manual time, since every change to the markup or the update function needs another listening pass.
This position was verified in October 2026 against Bootstrap 5.3.8. The advice changes if Bootstrap v6 drops the inner-bar ARIA placement, which the Bootstrap progress docs say works only until that release.