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

Rework progress bar markup and styles #36831

Merged
merged 21 commits into from
Nov 29, 2022
Merged

Rework progress bar markup and styles #36831

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
8dbd246
Rework progress bar markup and styles
patrickhlauke Jul 24, 2022
4c4397a
Merge branch 'main' into patrickhlauke-issue36736
patrickhlauke Jul 25, 2022
9aca783
Merge branch 'main' into patrickhlauke-issue36736
patrickhlauke Jul 29, 2022
5bf0ba6
Merge branch 'main' into patrickhlauke-issue36736
patrickhlauke Jul 30, 2022
88cd436
Add a note about progress bar change in migration guide
patrickhlauke Jul 30, 2022
ccd6dfb
Merge branch 'main' into patrickhlauke-issue36736
patrickhlauke Sep 17, 2022
b732f8d
Merge branch 'main' into patrickhlauke-issue36736
patrickhlauke Sep 24, 2022
181584c
Add notes with old markup examples and explanation
patrickhlauke Sep 25, 2022
d96f41f
Merge branch 'main' into patrickhlauke-issue36736
julien-deramond Nov 11, 2022
d830035
Fix bundlewatch
julien-deramond Nov 11, 2022
0d37033
Update site/content/docs/5.2/components/progress.md
patrickhlauke Nov 11, 2022
339b769
Merge branch 'main' into patrickhlauke-issue36736
patrickhlauke Nov 12, 2022
766a43c
Merge branch 'main' into patrickhlauke-issue36736
patrickhlauke Nov 12, 2022
0c55198
Reintroduce deleted styles
patrickhlauke Nov 12, 2022
2567144
Move changes in markup to Migrationg guide, link to that from top of …
mdo Nov 14, 2022
d20538b
Merge branch 'main' into patrickhlauke-issue36736
patrickhlauke Nov 14, 2022
7cc8fd8
Fix typo in callout
patrickhlauke Nov 14, 2022
ff19001
Clarify "Sizing" section
patrickhlauke Nov 14, 2022
16922c0
Remove redundant "now"
patrickhlauke Nov 14, 2022
f934f4e
Merge branch 'main' into patrickhlauke-issue36736
patrickhlauke Nov 28, 2022
a6e747b
Merge branch 'main' into patrickhlauke-issue36736
mdo Nov 29, 2022
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
11 changes: 10 additions & 1 deletion scss/_progress.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@
}
// scss-docs-end progress-keyframes

.progress {
.progress,
.progress-stacked {
// scss-docs-start progress-css-vars
--#{$prefix}progress-height: #{$progress-height};
@include rfs($progress-font-size, --#{$prefix}progress-font-size);
Expand Down Expand Up @@ -46,6 +47,14 @@
background-size: var(--#{$prefix}progress-height) var(--#{$prefix}progress-height);
}

.progress-stacked > .progress {
overflow: visible;
}

.progress-stacked > .progress > .progress-bar {
width: 100%;
}

@if $enable-transitions {
.progress-bar-animated {
animation: $progress-bar-animation-timing progress-bar-stripes;
Expand Down
119 changes: 67 additions & 52 deletions site/content/docs/5.2/components/progress.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,63 +6,72 @@ group: components
toc: true
---

{{< callout info >}}
**New markup in v5.3.0 —** We've deprecated the previous HTML structure for progress bars and replaced it with a more accessible one. The previous structure will continue to work until v6. [See what's changed in our migration guide.]({{< docsref "/migration#improved-markup-for-progress-bars" >}})
{{< /callout >}}

## How it works

Progress components are built with two HTML elements, some CSS to set the width, and a few attributes. We don't use [the HTML5 `<progress>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress), ensuring you can stack progress bars, animate them, and place text labels over them.

- We use the `.progress` as a wrapper to indicate the max value of the progress bar.
- We use the inner `.progress-bar` to indicate the progress so far.
- The `.progress-bar` requires an inline style, utility class, or custom CSS to set their width.
- The `.progress-bar` also requires some `role` and `aria` attributes to make it accessible, including an accessible name (using `aria-label`, `aria-labelledby`, or similar).
- The `.progress` wrapper also requires a `role="progress"` and `aria` attributes to make it accessible, including an accessible name (using `aria-label`, `aria-labelledby`, or similar).
- We use the inner `.progress-bar` purely for the visual bar and label.
- The `.progress-bar` requires an inline style, utility class, or custom CSS to set its width.
- We provide a special `.progress-stacked` class to create multiple/stacked progress bars.

Put that all together, and you have the following examples.

{{< example >}}
<div class="progress">
<div class="progress-bar" role="progressbar" aria-label="Basic example" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar" style="width: 0%"></div>
</div>
<div class="progress">
<div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 25%" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar" style="width: 25%"></div>
</div>
<div class="progress">
<div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 50%" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar" style="width: 50%"></div>
</div>
<div class="progress">
<div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 75%" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar" style="width: 75%"></div>
</div>
<div class="progress">
<div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 100%" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar" style="width: 100%"></div>
</div>
{{< /example >}}

Bootstrap provides a handful of [utilities for setting width]({{< docsref "/utilities/sizing" >}}). Depending on your needs, these may help with quickly configuring progress.
## Bar sizing

### Width
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand why this is modified like that but I've found it weird when I read it to have a "Sizing > Height" section that explains how to change the height of the entire progress bar and a "Sizing > Width" section that doesn't explain how to reduce the width of the progress bar but rather its content; its value.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can see what you mean, but in a sense both are about sizing the width and height of the bars themselves...just that the height is set for the whole of the progress element. Maybe changing the first heading to "Bar sizing"?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Made a tweak to the sizing section @julien-deramond @mdo to make it clearer

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK for me 👌


Bootstrap provides a handful of [utilities for setting width]({{< docsref "/utilities/sizing" >}}). Depending on your needs, these may help with quickly configuring the width of the `.progress-bar`.

{{< example >}}
<div class="progress">
<div class="progress-bar w-75" role="progressbar" aria-label="Basic example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar w-75"></div>
</div>
{{< /example >}}

## Labels
### Height

Add labels to your progress bars by placing text within the `.progress-bar`.
You only set a `height` value on the `.progress` container, so if you change that value, the inner `.progress-bar` will automatically resize accordingly.

{{< example >}}
<div class="progress">
<div class="progress-bar" role="progressbar" aria-label="Example with label" style="width: 25%;" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">25%</div>
<div class="progress" role="progressbar" aria-label="Example 1px high" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100" style="height: 1px">
<div class="progress-bar" style="width: 25%"></div>
</div>
<div class="progress" role="progressbar" aria-label="Example 20px high" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100" style="height: 20px">
<div class="progress-bar" style="width: 25%"></div>
</div>
{{< /example >}}

## Height
## Labels

We only set a `height` value on the `.progress`, so if you change that value the inner `.progress-bar` will automatically resize accordingly.
Add labels to your progress bars by placing text within the `.progress-bar`.

{{< example >}}
<div class="progress" style="height: 1px;">
<div class="progress-bar" role="progressbar" aria-label="Example 1px high" style="width: 25%;" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div>
</div>
<div class="progress" style="height: 20px;">
<div class="progress-bar" role="progressbar" aria-label="Example 20px high" style="width: 25%;" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress" role="progressbar" aria-label="Example with label" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar" style="width: 25%">25%</div>
</div>
{{< /example >}}

Expand All @@ -71,17 +80,17 @@ We only set a `height` value on the `.progress`, so if you change that value the
Use background utility classes to change the appearance of individual progress bars.

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

Expand All @@ -91,13 +100,19 @@ Use background utility classes to change the appearance of individual progress b

## Multiple bars

Include multiple progress bars in a progress component if you need.
You can include multiple progress components inside a container with `.progress-stacked` to create a single stacked progress bar. Note that in this case, the styling to set the visual width of the progress bar *must* be applied to the `.progress` elements, rather than the `.progress-bar`s.

{{< example >}}
<div class="progress">
<div class="progress-bar" role="progressbar" aria-label="Segment one" style="width: 15%" aria-valuenow="15" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress-bar bg-success" role="progressbar" aria-label="Segment two" style="width: 30%" aria-valuenow="30" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress-bar bg-info" role="progressbar" aria-label="Segment three" style="width: 20%" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress-stacked">
<div class="progress" role="progressbar" aria-label="Segment one" aria-valuenow="15" aria-valuemin="0" aria-valuemax="100" style="width: 15%">
<div class="progress-bar"></div>
</div>
<div class="progress" role="progressbar" aria-label="Segment two" aria-valuenow="30" aria-valuemin="0" aria-valuemax="100" style="width: 30%">
<div class="progress-bar bg-success"></div>
</div>
<div class="progress" role="progressbar" aria-label="Segment three" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100" style="width: 20%">
<div class="progress-bar bg-info"></div>
</div>
</div>
{{< /example >}}

Expand All @@ -106,20 +121,20 @@ Include multiple progress bars in a progress component if you need.
Add `.progress-bar-striped` to any `.progress-bar` to apply a stripe via CSS gradient over the progress bar's background color.

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

Expand All @@ -128,8 +143,8 @@ Add `.progress-bar-striped` to any `.progress-bar` to apply a stripe via CSS gra
The striped gradient can also be animated. Add `.progress-bar-animated` to `.progress-bar` to animate the stripes right to left via CSS3 animations.

{{< example >}}
<div class="progress">
<div class="progress-bar progress-bar-striped progress-bar-animated" role="progressbar" aria-label="Animated striped example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100" style="width: 75%"></div>
<div class="progress" role="progressbar" aria-label="Animated striped example" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar progress-bar-striped progress-bar-animated" style="width: 75%"></div>
</div>
{{< /example >}}

Expand Down
30 changes: 17 additions & 13 deletions site/content/docs/5.2/examples/cheatsheet-rtl/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1397,27 +1397,31 @@ <h3>شريط التقدم</h3>

<div>
{{< example show_markup="false" >}}
<div class="progress mb-3">
<div class="progress-bar" role="progressbar" aria-label="مثال مع عنوان" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100">0%</div>
<div class="progress mb-3" role="progressbar" aria-label="مثال مع عنوان" aria-valuenow="0" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar">0%</div>
</div>
<div class="progress mb-3">
<div class="progress-bar bg-success w-25" role="progressbar" aria-label="مثال ناجح مع عنوان" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">25%</div>
<div class="progress mb-3" role="progressbar" aria-label="مثال ناجح مع عنوان" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar bg-success w-25">25%</div>
</div>
<div class="progress mb-3">
<div class="progress-bar text-bg-info w-50" role="progressbar" aria-label="مثال توضيح مع عنوان" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">50%</div>
<div class="progress mb-3" role="progressbar" aria-label="مثال توضيح مع عنوان" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar text-bg-info w-50">50%</div>
</div>
<div class="progress mb-3">
<div class="progress-bar text-bg-warning w-75" role="progressbar" aria-label="مثال تنبيه مع عنوان" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">75%</div>
<div class="progress mb-3" role="progressbar" aria-label="مثال تنبيه مع عنوان" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar text-bg-warning w-75">75%</div>
</div>
<div class="progress">
<div class="progress-bar bg-danger w-100" role="progressbar" aria-label="مثال خطر مع عنوان" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100">100%</div>
<div class="progress" role="progressbar" aria-label="مثال خطر مع عنوان" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar bg-danger w-100">100%</div>
</div>
{{< /example >}}

{{< example show_markup="false" >}}
<div class="progress">
<div class="progress-bar" role="progressbar" aria-label="القسم الأول - مثال افتراضي" style="width: 15%" aria-valuenow="15" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress-bar progress-bar-striped progress-bar-animated bg-success" role="progressbar" aria-label="القسم الثاني - مثال ناجح مقلّم متحرك" style="width: 40%" aria-valuenow="40" aria-valuemin="0" aria-valuemax="100"></div>
<div class="progress-stacked">
<div class="progress" role="progressbar" aria-label="القسم الأول - مثال افتراضي" style="width: 15%" aria-valuenow="15" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar"></div>
</div>
<div class="progress" role="progressbar" aria-label="القسم الثاني - مثال ناجح مقلّم متحرك" style="width: 40%" aria-valuenow="40" aria-valuemin="0" aria-valuemax="100">
<div class="progress-bar progress-bar-striped progress-bar-animated bg-success"></div>
</div>
</div>
{{< /example >}}
</div>
Expand Down
Loading