Progress
Display task progress with accessible labels, stacked bars, contextual colors, and animation.
<div class="vstack gap-3" style="width: min(100%, 32rem);">
<twig:Progress value="25" ariaLabel="Project setup" label="25%" />
<twig:Progress value="50" ariaLabel="Content migration" color="success" striped label="50%" />
<twig:Progress value="75" ariaLabel="Deployment" color="info" striped animated label="75%" />
</div>
Installation
php bin/console ux:install progress --kit bootstrap
Install the following Composer dependencies:
composer require twig/extra-bundle twig/html-extra:^3.12.0
Install the following front-end dependencies:
npm install bootstrap@^5.3.0
# ...or with Symfony AssetMapper
php bin/console importmap:require bootstrap bootstrap/dist/css/bootstrap.min.css
Copy the following file(s) into your app:
{# @prop value number The current progress value. #}
{# @prop min number The minimum progress value. #}
{# @prop max number The maximum progress value. #}
{# @prop ariaLabel string The accessible name of the progress indicator. #}
{# @prop label string The fallback text displayed inside the bar. #}
{# @prop color 'primary'|'secondary'|'success'|'danger'|'warning'|'info'|'light'|'dark'|null The Bootstrap background color. #}
{# @prop striped boolean Whether to display striped styling. #}
{# @prop animated boolean Whether to animate striped styling. #}
{# @prop height string|null The custom height of the progress container. #}
{# @prop barWidth string|false|null The CSS width of the visual bar, or false to omit it. #}
{# @prop barClass string The additional classes applied to the visual bar. #}
{# @prop stacked boolean Whether this progress indicator is a segment within a stacked progress bar. #}
{# @block content The text or custom content displayed inside the visual bar. #}
{%- props
value = 0,
min = 0,
max = 100,
ariaLabel = 'Progress',
label = '',
color = null,
striped = false,
animated = false,
height = null,
barWidth = null,
barClass = '',
stacked = false
-%}
{%- set bar_classes = html_classes({
'progress-bar': true,
('bg-' ~ color): color in ['primary', 'secondary', 'success', 'danger', 'warning', 'info', 'light', 'dark'],
'progress-bar-striped': striped,
'progress-bar-animated': animated and striped,
(barClass): barClass != '',
}) -%}
{%- set root_attrs = {
class: 'progress',
role: 'progressbar',
'aria-label': ariaLabel,
'aria-valuenow': value,
'aria-valuemin': min,
'aria-valuemax': max,
} -%}
{%- if stacked -%}
{%- set root_attrs = root_attrs|merge({style: 'width: ' ~ value ~ '%'}) -%}
{%- elseif height not in [null, ''] -%}
{%- set root_attrs = root_attrs|merge({style: 'height: ' ~ height}) -%}
{%- endif -%}
{%- set final_bar_width = stacked or barWidth is same as(false) ? null : (barWidth ?? (value ~ '%')) -%}
<div {{ attributes.defaults(root_attrs) }}>
<div
class="{{ bar_classes }}"
{%- if final_bar_width is not null %} style="width: {{ final_bar_width }}"{% endif %}
>
{%- block content -%}
{{- label -}}
{%- endblock -%}
</div>
</div>
Usage
<twig:Progress value="25" ariaLabel="File upload progress" label="25%" />
Accessibility
Give every progress indicator a concise accessible name with ariaLabel. Keep value, min, and max synchronized with the task's real state.
Do not rely on color alone to communicate status. Long labels can cross both the filled and unfilled backgrounds, so prefer a separate visible label when contrast cannot be guaranteed.
Examples
How it works
Set the current value to update both the visual width and the progressbar accessibility attributes.
<div class="vstack gap-2">
{% for value in [0, 25, 50, 75, 100] %}
<twig:Progress :value="value" ariaLabel="Basic example" />
{% endfor %}
</div>
Width
Use Bootstrap width utilities when the visual width should be controlled by a class.
<div class="w-100">
<twig:Progress value="75" ariaLabel="Width utility example" barClass="w-75" :barWidth="false" />
</div>
Height
Set a custom height on the progress container.
<div class="vstack gap-3">
<twig:Progress value="25" ariaLabel="Example 1px high" height="1px" />
<twig:Progress value="25" ariaLabel="Example 20px high" height="20px" />
</div>
Labels
Display short text inside the bar, with care for overflow and contrast when labels are long.
<div class="vstack gap-3">
<twig:Progress value="25" ariaLabel="Example with label" label="25%" />
<twig:Progress
value="10"
ariaLabel="Example with long label"
label="Long label text for the progress bar"
barClass="overflow-visible text-dark"
/>
</div>
Backgrounds
Apply contextual background colors, with matching text-background helpers for labeled bars.
<div class="vstack gap-3">
<twig:Progress value="25" ariaLabel="Success example" color="success" />
<twig:Progress value="50" ariaLabel="Info example" color="info" />
<twig:Progress value="75" ariaLabel="Warning example" color="warning" />
<twig:Progress value="100" ariaLabel="Danger example" color="danger" />
<twig:Progress value="25" ariaLabel="Labeled success example" barClass="text-bg-success" label="25%" />
<twig:Progress value="50" ariaLabel="Labeled info example" barClass="text-bg-info" label="50%" />
<twig:Progress value="75" ariaLabel="Labeled warning example" barClass="text-bg-warning" label="75%" />
<twig:Progress value="100" ariaLabel="Labeled danger example" barClass="text-bg-danger" label="100%" />
</div>
Multiple bars
Wrap stacked progress segments in Bootstrap's progress-stacked container.
<div class="progress-stacked">
<twig:Progress value="15" ariaLabel="Segment one" stacked />
<twig:Progress value="30" ariaLabel="Segment two" color="success" stacked />
<twig:Progress value="20" ariaLabel="Segment three" color="info" stacked />
</div>
Striped
Add striped styling to default and contextual progress bars.
<div class="vstack gap-3">
<twig:Progress value="10" ariaLabel="Default striped example" striped />
<twig:Progress value="25" ariaLabel="Success striped example" color="success" striped />
<twig:Progress value="50" ariaLabel="Info striped example" color="info" striped />
<twig:Progress value="75" ariaLabel="Warning striped example" color="warning" striped />
<twig:Progress value="100" ariaLabel="Danger striped example" color="danger" striped />
</div>
Animated stripes
Animate a striped bar to emphasize an actively changing task.
<div class="w-100">
<twig:Progress value="75" ariaLabel="Animated striped example" striped animated />
</div>
API Reference
<twig:Progress>
| Prop | Type | Default |
|---|---|---|
value The current progress value.
|
number |
0 |
min The minimum progress value.
|
number |
0 |
max The maximum progress value.
|
number |
100 |
ariaLabel The accessible name of the progress indicator.
|
string |
'Progress' |
label The fallback text displayed inside the bar.
|
string |
'' |
color The Bootstrap background color.
|
'primary'|'secondary'|'success'|'danger'|'warning'|'info'|'light'|'dark'|null |
null |
striped Whether to display striped styling.
|
boolean |
false |
animated Whether to animate striped styling.
|
boolean |
false |
height The custom height of the progress container.
|
string|null |
null |
barWidth The CSS width of the visual bar, or false to omit it.
|
string|false|null |
null |
barClass The additional classes applied to the visual bar.
|
string |
'' |
stacked Whether this progress indicator is a segment within a stacked progress bar.
|
boolean |
false |
| Block | Description |
|---|---|
content |
The text or custom content displayed inside the visual bar. |