Skip to content

Commit 39b7c75

Browse files
jaumesalaXhmikosRmdopatrickhlauke
authored
Add new placeholder component (#31859)
Co-authored-by: XhmikosR <xhmikosr@gmail.com> Co-authored-by: Jaume Sala <jaumesala@gmail.com> Co-authored-by: Mark Otto <markdotto@gmail.com> Co-authored-by: Patrick H. Lauke <redux@splintered.co.uk>
1 parent f64df40 commit 39b7c75

File tree

6 files changed

+215
-0
lines changed

6 files changed

+215
-0
lines changed

‎scss/_placeholders.scss

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
.placeholder {
2+
display: inline-block;
3+
min-height: 1em;
4+
vertical-align: middle;
5+
cursor: wait;
6+
background-color: currentColor;
7+
opacity: $placeholder-opacity-max;
8+
9+
&.btn::before {
10+
display: inline-block;
11+
content: "";
12+
}
13+
}
14+
15+
// Sizing
16+
.placeholder-xs {
17+
min-height: .6em;
18+
}
19+
20+
.placeholder-sm {
21+
min-height: .8em;
22+
}
23+
24+
.placeholder-lg {
25+
min-height: 1.2em;
26+
}
27+
28+
// Animation
29+
.placeholder-glow {
30+
.placeholder {
31+
animation: placeholder-glow 2s ease-in-out infinite;
32+
}
33+
}
34+
35+
@keyframes placeholder-glow {
36+
50% {
37+
opacity: $placeholder-opacity-min;
38+
}
39+
}
40+
41+
.placeholder-wave {
42+
mask-image: linear-gradient(130deg, $black 55%, rgba(0, 0, 0, (1 - $placeholder-opacity-min)) 75%, $black 95%);
43+
mask-size: 200% 100%;
44+
animation: placeholder-wave 2s linear infinite;
45+
}
46+
47+
@keyframes placeholder-wave {
48+
100% {
49+
mask-position: -200% 0%;
50+
}
51+
}

‎scss/_variables.scss

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1203,6 +1203,13 @@ $pagination-border-radius-lg: $border-radius-lg !default;
12031203
// scss-docs-end pagination-variables
12041204

12051205

1206+
// Placeholders
1207+
1208+
// scss-docs-start placeholders
1209+
$placeholder-opacity-max: .5 !default;
1210+
$placeholder-opacity-min: .2 !default;
1211+
// scss-docs-end placeholders
1212+
12061213
// Cards
12071214

12081215
// scss-docs-start card-variables

‎scss/bootstrap.scss

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@
4343
@import "carousel";
4444
@import "spinners";
4545
@import "offcanvas";
46+
@import "placeholders";
4647

4748
// Helpers
4849
@import "helpers";

‎site/assets/scss/_component-examples.scss

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -292,6 +292,17 @@
292292
}
293293
}
294294

295+
// Placeholders
296+
.bd-example-placeholder-cards {
297+
&::after {
298+
display: none;
299+
}
300+
301+
.card {
302+
width: 18rem;
303+
}
304+
}
305+
295306
// Toasts
296307
.bd-example-toasts {
297308
min-height: 240px;

‎site/content/docs/5.0/components/placeholders.md

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
layout: docs
3+
title: Placeholders
4+
description: Use loading placeholders for your components or pages to indicate something may still be loading.
5+
group: components
6+
toc: true
7+
---
8+
9+
## About
10+
11+
Placeholders can be used to enhance the experience of your application. They're built only with HTML and CSS, meaning you don't need any JavaScript to create them. You will, however, need some custom JavaScript to toggle their visibility. Their appearance, color, and sizing can be easily customized with our utility classes.
12+
13+
## Example
14+
15+
In the example below, we take a typical card component and recreate it with placeholders applied to create a "loading card". Size and proportions are the same between the two.
16+
17+
<div class="bd-example bd-example-placeholder-cards d-flex justify-content-around">
18+
<div class="card">
19+
{{< placeholder width="100%" height="180" class="card-img-top" text="false" background="#20c997" >}}
20+
<div class="card-body">
21+
<h5 class="card-title">Card title</h5>
22+
<p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
23+
<a href="#" class="btn btn-primary">Go somewhere</a>
24+
</div>
25+
</div>
26+
27+
<div class="card" aria-hidden="true">
28+
{{< placeholder width="100%" height="180" class="card-img-top" text="false" >}}
29+
<div class="card-body">
30+
<div class="h5 card-title placeholder-glow">
31+
<span class="placeholder col-6"></span>
32+
</div>
33+
<p class="card-text placeholder-glow">
34+
<span class="placeholder col-7"></span>
35+
<span class="placeholder col-4"></span>
36+
<span class="placeholder col-4"></span>
37+
<span class="placeholder col-6"></span>
38+
<span class="placeholder col-8"></span>
39+
</p>
40+
<a href="#" tabindex="-1" class="btn btn-primary disabled placeholder col-6"></a>
41+
</div>
42+
</div>
43+
</div>
44+
45+
```html
46+
<div class="card">
47+
<img src="..." class="card-img-top" alt="...">
48+
49+
<div class="card-body">
50+
<h5 class="card-title">Card title</h5>
51+
<p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
52+
<a href="#" class="btn btn-primary">Go somewhere</a>
53+
</div>
54+
</div>
55+
56+
<div class="card" aria-hidden="true">
57+
<img src="..." class="card-img-top" alt="...">
58+
<div class="card-body">
59+
<h5 class="card-title placeholder-glow">
60+
<span class="placeholder col-6"></span>
61+
</h5>
62+
<p class="card-text placeholder-glow">
63+
<span class="placeholder col-7"></span>
64+
<span class="placeholder col-4"></span>
65+
<span class="placeholder col-4"></span>
66+
<span class="placeholder col-6"></span>
67+
<span class="placeholder col-8"></span>
68+
</p>
69+
<a href="#" tabindex="-1" class="btn btn-primary disabled placeholder col-6"></a>
70+
</div>
71+
</div>
72+
```
73+
74+
## How it works
75+
76+
Create placeholders with the `.placeholder` class and a grid column class (e.g., `.col-6`) to set the `width`. They can replace the text inside an element or as be added as a modifier class to an existing component.
77+
78+
We apply additional styling to `.btn`s via `::before` to ensure the `height` is respected. You may extend this pattern for other situations as needed, or add a `&nbsp;` within the element to reflect the height when actual text is rendered in its place.
79+
80+
{{< example >}}
81+
<p aria-hidden="true">
82+
<span class="placeholder col-6"></span>
83+
</p>
84+
85+
<a href="#" class="btn btn-primary disabled placeholder col-4" aria-hidden="true"></a>
86+
{{< /example >}}
87+
88+
{{< callout info >}}
89+
The use of `aria-hidden="true"` only indicates that the element should be hidden to screen readers. The *loading* behaviour of the placeholder depends on how authors will actually use the placeholder styles, how they plan to update things, etc. Some JavasSript code may be needed to *swap* the state of the placeholder and inform AT users of the update.
90+
{{< /callout >}}
91+
92+
### Width
93+
94+
You can change the `width` through grid column classes, width utilities, or inline styles.
95+
96+
{{< example >}}
97+
<span class="placeholder col-6"></span>
98+
<span class="placeholder w-75"></span>
99+
<span class="placeholder" style="width: 25%;"></span>
100+
{{< /example >}}
101+
102+
### Color
103+
104+
By default, the `placeholder` uses `currentColor`. This can be overriden with a custom color or utility class.
105+
106+
{{< example >}}
107+
<span class="placeholder col-12"></span>
108+
{{< placeholders.inline >}}
109+
{{- range (index $.Site.Data "theme-colors") }}
110+
<span class="placeholder col-12 bg-{{ .name }}"></span>
111+
{{- end -}}
112+
{{< /placeholders.inline >}}
113+
{{< /example >}}
114+
115+
### Sizing
116+
117+
The size of `.placeholder`s are based on the typographic style of the parent element. Customize them with sizing modifiers: `.placeholder-lg`, `.placeholder-sm`, or `.placeholder-xs`.
118+
119+
{{< example >}}
120+
<span class="placeholder col-12 placeholder-lg"></span>
121+
<span class="placeholder col-12"></span>
122+
<span class="placeholder col-12 placeholder-sm"></span>
123+
<span class="placeholder col-12 placeholder-xs"></span>
124+
{{< /example >}}
125+
126+
### Animation
127+
128+
Animate placehodlers with `.placeholder-glow` or `.placeholder-wave` to better convey the perception of something being _actively_ loaded.
129+
130+
{{< example >}}
131+
<p class="placeholder-glow">
132+
<span class="placeholder col-12"></span>
133+
</p>
134+
135+
<p class="placeholder-wave">
136+
<span class="placeholder col-12"></span>
137+
</p>
138+
{{< /example >}}
139+
140+
## Sass
141+
142+
### Variables
143+
144+
{{< scss-docs name="placeholders" file="scss/_variables.scss" >}}

‎site/data/sidebar.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@
7575
- title: Navbar
7676
- title: Offcanvas
7777
- title: Pagination
78+
- title: Placeholders
7879
- title: Popovers
7980
- title: Progress
8081
- title: Scrollspy

0 commit comments

Comments
 (0)