Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: improve progress bar labels markup and explanations for accessibility #39364

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Docs: improve progress bar labels markup and explanations for accessibility #39364

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3a745aa
Docs: improve progress bar labels markup and explanations for accessi…
julien-deramond Nov 3, 2023
efd2ac3
Merge branch 'main' into main-jd-color-modes-progress-bars
patrickhlauke Nov 15, 2023
90e449b
Merge branch 'main' into main-jd-color-modes-progress-bars
mdo Jan 11, 2024
ec0f3b7
Merge branch 'main' into main-jd-color-modes-progress-bars
patrickhlauke May 24, 2024
aebd50a
Update site/content/docs/5.3/components/progress.md
mdo Feb 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 13 additions & 19 deletions site/content/docs/5.3/components/progress.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,13 +75,15 @@ Add labels to your progress bars by placing text within the `.progress-bar`.
</div>
{{< /example >}}

Note that by default, the content inside the `.progress-bar` is controlled with `overflow: hidden`, so it doesn't bleed out of the bar. If your progress bar is shorter than its label, the content will be capped and may become unreadable. To change this behavior, you can use `.overflow-visible` from the [overflow utilities]({{< docsref "/utilities/overflow" >}}), but make sure to also define an explicit [text color]({{< docsref "/utilities/colors#colors" >}}) so the text remains readable. Be aware though that currently this approach does not take into account [color modes]({{< docsref "/customize/color-modes" >}}).
### Long labels

{{< example >}}
<div class="progress" role="progressbar" aria-label="Example with label" aria-valuenow="10" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar overflow-visible text-dark" style="width: 10%">Long label text for the progress bar, set to a dark color</div>
</div>
{{< /example >}}
Note that by default, the content inside the `.progress-bar` is controlled with `overflow: hidden`, so it doesn't bleed out of the bar. If your progress bar is shorter than its label, the content will be capped and may become unreadable. To change this behavior, you can use `.overflow-visible` from the [overflow utilities]({{< docsref "/utilities/overflow" >}}).

{{< callout warning >}}
Labels longer than the progress bar within may not be fully accessible using this method because it relies on the text color having the correct contrast ratio with both the `.progress` and `.progress-bar` background colors. Use caution when implementing this example.

If the text can overlap the progress bar, we often recommend displaying the label outside of the progress bar for better accessibility.
{{< /callout >}}

## Backgrounds

Expand All @@ -106,28 +108,20 @@ Use background utility classes to change the appearance of individual progress b
{{< partial "callouts/warning-color-assistive-technologies.md" >}}
{{< /callout >}}

If you're adding labels to progress bars with a custom background color, make sure to also set an appropriate [text color]({{< docsref "/utilities/colors#colors" >}}), so the labels remain readable and have sufficient contrast.
If you're adding labels to progress bars with a custom background color, make sure to also set an appropriate [text color]({{< docsref "/utilities/colors#colors" >}}), so the labels remain readable and have sufficient contrast. We recommend using the [color and background]({{< docsref "/helpers/color-background" >}}) helper classes.

{{< example >}}
<div class="progress" role="progressbar" aria-label="Success example" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar bg-success" style="width: 25%">25%</div>
<div class="progress-bar text-bg-success" style="width: 25%">25%</div>
</div>
<div class="progress" role="progressbar" aria-label="Info example" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar bg-info text-dark" style="width: 50%">50%</div>
<div class="progress-bar text-bg-info" style="width: 50%">50%</div>
</div>
<div class="progress" role="progressbar" aria-label="Warning example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar bg-warning text-dark" style="width: 75%">75%</div>
<div class="progress-bar text-bg-warning" style="width: 75%">75%</div>
</div>
<div class="progress" role="progressbar" aria-label="Danger example" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar bg-danger" style="width: 100%">100%</div>
</div>
{{< /example >}}

Alternatively, you can use the new combined [color and background]({{< docsref "/helpers/color-background" >}}) helper classes.

{{< example >}}
<div class="progress" role="progressbar" aria-label="Warning example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar text-bg-warning" style="width: 75%">75%</div>
<div class="progress-bar text-bg-danger" style="width: 100%">100%</div>
</div>
{{< /example >}}

Expand Down
Loading