Skip to content

Update placeholder sizing, docs, and animations #42882

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

Open
mdo wants to merge 2 commits into
base: v6-dev
Choose a base branch
from
+36 −17
Open

Update placeholder sizing, docs, and animations #42882

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0cfd0d3
Update placeholder sizing, docs, and animations
mdo Mar 5, 2026
6a708d0
fix(css): drop unused colors import from placeholder
mdo Aug 31, 2026
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
29 changes: 21 additions & 8 deletions scss/_placeholder.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,41 @@
@use "colors" as *;
@use "config" as *;
@use "functions" as *;
@use "mixins/border-radius" as *;
@use "mixins/tokens" as *;

$placeholder-tokens: () !default;
$placeholder-wave-tokens: () !default;

// scss-docs-start placeholder-tokens
// stylelint-disable-next-line scss/dollar-variable-default
$placeholder-tokens: defaults(
(
--placeholder-opacity-max: .5,
--placeholder-opacity-min: .2,
--placeholder-opacity-max: .18,
--placeholder-opacity-min: .1,
),
$placeholder-tokens
);

// stylelint-disable-next-line scss/dollar-variable-default
$placeholder-wave-tokens: defaults(
(
--placeholder-opacity-max: .5,
--placeholder-opacity-min: .25,
),
$placeholder-wave-tokens
);
// scss-docs-end placeholder-tokens

@layer components {
.placeholder {
@include tokens($placeholder-tokens);

display: inline-block;
min-height: 1em;
min-height: 1.25em;
vertical-align: middle;
cursor: wait;
background-color: currentcolor;
@include border-radius(var(--radius-3));
opacity: var(--placeholder-opacity-max);

&.btn::before {
Expand All @@ -35,15 +46,15 @@ $placeholder-tokens: defaults(

// Sizing
.placeholder-xs {
min-height: .6em;
min-height: .75em;
}

.placeholder-sm {
min-height: .8em;
min-height: 1em;
}

.placeholder-lg {
min-height: 1.2em;
min-height: 1.75em;
}

// Animation
Expand All @@ -66,7 +77,9 @@ $placeholder-tokens: defaults(
}

.placeholder-wave {
mask-image: linear-gradient(130deg, $black 55%, rgb(0 0 0 / calc(1 - var(--placeholder-opacity-min))) 75%, $black 95%);
@include tokens($placeholder-wave-tokens);

mask-image: linear-gradient(110deg, var(--black) 40%, rgb(0 0 0 / calc(1 - var(--placeholder-opacity-max))) 50%, var(--black) 60%);
mask-size: 200% 100%;
animation: placeholder-wave 2s linear infinite;

Expand Down
24 changes: 15 additions & 9 deletions site/src/content/docs/components/placeholder.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ In the example below, we take a typical card component and recreate it with plac
<span class="placeholder col-6"></span>
<span class="placeholder col-8"></span>
</p>
<a class="btn-solid theme-primary disabled placeholder col-6" aria-disabled="true"></a>
<a class="btn-solid theme-primary disabled col-6" aria-disabled="true"></a>
</div>
</div>`} />

Expand Down Expand Up @@ -82,40 +82,40 @@ We apply additional styling to `.btn`s via `::before` to ensure the `height` is
<span class="placeholder col-6"></span>
</p>

<a class="btn-solid theme-primary disabled placeholder col-4" aria-disabled="true"></a>`} />
<a class="btn-solid theme-primary disabled col-4" aria-disabled="true"></a>`} />

<Callout>
The use of `aria-hidden="true"` only indicates that the element should be hidden to screen readers. The *loading* behavior of the placeholder depends on how authors will actually use the placeholder styles, how they plan to update things, etc. Some JavaScript code may be needed to *swap* the state of the placeholder and inform AT users of the update.
</Callout>

### Width
## Width

You can change the `width` through grid column classes, width utilities, or inline styles.

<Example code={`<span class="placeholder col-6"></span>
<span class="placeholder w-75"></span>
<span class="placeholder" style="width: 25%;"></span>`} />

### Color
## Color

By default, the `placeholder` uses `currentColor`. This can be overridden with a custom color or utility class.

<Example code={[
`<span class="placeholder col-12"></span>
`<span class="placeholder col-9"></span>
`,
...getData('theme-colors').map((themeColor) => `<span class="placeholder col-12 bg-${themeColor.name}"></span>`)
...getData('theme-colors').map((themeColor) => `<span class="placeholder col-6 bg-${themeColor.name}"></span>`)
]} />

### Sizing
## Sizing

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`.

<Example code={`<span class="placeholder col-12 placeholder-lg"></span>
<Example class="vstack gap-2" code={`<span class="placeholder col-12 placeholder-lg"></span>
<span class="placeholder col-12"></span>
<span class="placeholder col-12 placeholder-sm"></span>
<span class="placeholder col-12 placeholder-xs"></span>`} />

### Animation
## Animation

Animate placeholders with `.placeholder-glow` or `.placeholder-wave` to better convey the perception of something being *actively* loaded.

Expand All @@ -127,6 +127,12 @@ Animate placeholders with `.placeholder-glow` or `.placeholder-wave` to better c
<span class="placeholder col-12"></span>
</p>`} />

### Text

Add `placeholder-wave` to an inline element with text to apply the placeholder animations to the text.

<Example code={`<span class="placeholder-wave fg-3">Working on it…</span>`} />

## CSS

### Variables
Expand Down