Skip to content
BlazorUI

Progress

Shimmer

Bit.BlazorUISkeleton

Shimmer is a loading placeholder for content that has not arrived yet, so a page lays itself out before its data is in. It draws a bar, a paragraph, a pill, a circle or a template of shimmers, can cover content that is being refreshed, holds the placeholder back from fast responses, and tells screen readers when the wait is over.

Notes

The shimmer honors the reduced motion preference of the OS/browser (prefers-reduced-motion) by stopping its animation and leaving the static block behind. If nothing on this page is moving, turn the reduce motion setting off, use the ForceAnimation parameter, or turn on the ForceAnimation toggle at the top of this page.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

A full-width rounded bar with the wave. Height sizes the placeholder only - the loaded content decides its own - while Width stays with the component, so the placeholder and its content share a column.


Height

Width

Shape & radius

Shape the placeholder like what it waits for: Rounded (default) for text and blocks, Square for edge-to-edge images, Pill for buttons and tags, Circle for avatars (Circle="true" is the short form). A circle takes its diameter from Height or Width.
Radius sets any other corner, such as the one of the card the content lands on, and wins over the shape.

Rounded (default), Square and Pill

Circle

Radius="1rem", and Radius="0" over a Pill

Lines

Lines stacks the shimmer into a paragraph: each line is Height tall, Gap apart, and the last one is shortened to LastLineWidth (60% by default). LineWidths gives the lines a measure each, from the first one on.

Lines="3"

Gap and LastLineWidth

Even rows

LineWidths

Animation

Wave (default) sweeps a band across the box, Pulse breathes (Pulse="true" is the short form), Fade breathes all the way out, and None is a static block for long lists.
Duration is one loop in ms and Delay the pause before the first. Stagger offsets each line of a stack by that many ms, so a paragraph arrives line by line.

Wave (default)

Pulse

Fade

None

Duration="5000" Delay="1000"

Stagger="200"

Inline

Inline places the shimmer in a line of text, rendered as a span so the paragraph stays valid. It falls back to the theme's minimum control width, and Height="1em" matches the surrounding type.

The plan costs per month and renews on .

Loaded

Loaded swaps the placeholder for its content (ChildContent, or Content), which is laid out by the page rather than by the placeholder's size. The content fades in only after a placeholder was seen; loaded from the start, it just appears.


ShowDelay & MinShowTime

ShowDelay keeps a fast response from flashing a placeholder; the wait is pure CSS, so it also works under static SSR. MinShowTime keeps a placeholder that did appear from vanishing in a blink. Press each button and compare the three.


Without ShowDelay
The response is in.

ShowDelay="1000"
The response is in.

ShowDelay="1000" MinShowTime="1000"
The response is in.

Overlay

Overlay lays the placeholder over content that is already on the page, so a refresh never moves the layout. The covered content keeps its size and its state - it is covered, never re-created - but is hidden from sight, the tab order and screen readers. Lines and Template do not apply.

Overlay
Monthly revenue

$48,120

Up 12% on the previous month.

In place, for comparison

Template

Template draws a skeleton out of shimmers of its own, laid out like the content. The outer shimmer's shape, lines and animation no longer apply, but its ShowDelay holds the whole skeleton back as one.



Accessibility

The shimmer is aria-busy while it waits and hides its empty boxes from assistive technologies. Label adds a screen-reader-only live region that switches to LoadedLabel when the content arrives, and that switch is announced - set it on the one shimmer that stands for a region, with Politeness for its urgency. AriaLabel names the placeholder quietly, as an indeterminate progressbar until it is loaded.

Loading your profile

Cascading parameters

BitParams hands a BitShimmerParams to every shimmer under it, so a skeleton sets its look and timing once. The values are defaults, not overrides: a parameter a shimmer sets itself wins. Loaded, the content and the labels stay per shimmer.

Takes the pulse, the line height, the last line and the stagger from the cascade

Its own animation and height, the cascaded rest

Outside the cascade, back to the defaults

Color

Color paints the animated part - the wave band, or the block the pulse and the fade play on - and Background the resting box beneath it, which is all a None placeholder shows. Keep the two close: a high-contrast pair reads as content.

Color Background
Primary
Secondary
Tertiary
Info
Success
Warning
SevereWarning
Error
PrimaryBackground
SecondaryBackground (default Background)
TertiaryBackground (default Color)
PrimaryForeground
SecondaryForeground
TertiaryForeground
PrimaryBorder
SecondaryBorder
TertiaryBorder

Size

Size sets the default line height and circle diameter. An explicit Height or Width wins over it.

Small

Medium (default)

Large

Style & Class

Style and Class reach the root; Styles and Classes reach each part: the root, every line's wrapper, the animated part, the content and the live region.

Component's Style & Class:






Styles & Classes:






CSS variables inherit: set one on :root to restyle every shimmer, on an ancestor to restyle a skeleton, or on the Style of a single shimmer. A parameter written on a shimmer wins.



RTL

Use Dir="BitDir.Rtl" for right-to-left: the wave sweeps in from the right and the last line of a stack stops short of the left edge.


CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.

BitShimmer CSS variables

Name Default value Description
--bit-Shimmer-background --bit-clr-bg-sec Resting color of the placeholder, which the animation plays over. The Background parameter wins over it.
--bit-Shimmer-color --bit-clr-bg-ter Color of the animated part: the wave band, or the block the pulse and the fade play on. The Color parameter wins over it.
--bit-Shimmer-height spacing(4) Height of a line. The Height and Size parameters win over it.
--bit-Shimmer-circle-size --bit-siz-ctrl-md Diameter of a circle. The Height and Size parameters win over it.
--bit-Shimmer-radius --bit-shp-radius-surface Corner of a Rounded placeholder. The Radius parameter and the Square and Pill shapes win over it.
--bit-Shimmer-gap spacing(1) Room between the lines of a stack. The Gap parameter wins over it.
--bit-Shimmer-last-line-width 60% Width of the last line of a stack. The LastLineWidth and LineWidths parameters win over it.
--bit-Shimmer-animation-duration 1.6s x --bit-mot-loop-factor One loop of the wave, the pulse or the fade. The Duration parameter wins over it.
--bit-Shimmer-animation-delay 0.5s x --bit-mot-loop-factor Pause before the first loop. The Delay and Stagger parameters win over it.

API

Every parameter, public member, sub-class and enum this component exposes.

BitShimmer parameters

Name Type Default value Description
Animation BitShimmerAnimation? null The animation the shimmer plays while it waits: Wave, Pulse, Fade or None.
Background BitColor? null The resting color of the placeholder, which the animation plays over. It is all a None placeholder shows.
ChildContent RenderFragment? null The content that replaces the shimmer once Loaded is true.
Circle bool false Renders the shimmer as a circle. Short form of Shape="BitShape.Circle", which wins over it.
Classes BitShimmerClassStyles? null Custom CSS classes for different parts of the BitShimmer.
Color BitColor? null The color of the animated part of the shimmer. A None placeholder has no animated part.
Content RenderFragment? null Alias of ChildContent.
Delay int? null The pause in ms before the first loop of the animation. Not the wait before the placeholder appears (see ShowDelay).
Duration int? null The length in ms of one loop of the animation.
Gap string? null The gap between the lines of a multi-line shimmer, as a CSS length.
Height string? null The height of the placeholder, or of each line of a multi-line one. Dropped once loaded, so the content sizes itself. Defaults to the Size.
Inline bool false Lays the shimmer out in a line of text, rendered as a span. Without a Width it takes the theme's minimum control width.
Label string? null Screen-reader text announced while the shimmer waits, in a live region that switches to LoadedLabel when the content arrives. The region is rendered right after the root, so a sibling selector sees it too, and it follows the root's Visibility, hidden, inert, aria-hidden, Dir and lang but not a stylesheet that hides it.
LastLineWidth string? null The width of the last line of a multi-line shimmer, as a CSS length. Defaults to 60%.
Lines int 1 The number of lines stacked as a paragraph. A circle and an overlay ignore it.
LineWidths IList<string>? null The width of each line of a multi-line shimmer, from the first line on. Lines past the end of the list keep their default width.
Loaded bool false Swaps the placeholder for the content, which fades in if a placeholder was seen.
LoadedLabel string? null Screen-reader text announced once the content has replaced the shimmer.
MinShowTime int? null The shortest time in ms a placeholder that has appeared stays on the page, so a response landing just after it never flickers.
Overlay bool false Draws the placeholder over the content instead of in place of it, so the layout never moves and the content keeps its state. Lines and Template do not apply. Covered content leaves the tab order, so keep the control that starts a refresh outside it.
Politeness BitPoliteness BitPoliteness.Polite How urgently the live region interrupts a screen reader. Only applies with Label or LoadedLabel.
Pulse bool false Changes the animation to pulse. Short form of Animation="BitShimmerAnimation.Pulse", which wins over it.
Radius string? null The corner radius of the placeholder, as a CSS length. Wins over the Shape; a circle ignores it.
Shape BitShape? null The shape of the placeholder: Rounded, Square, Pill or Circle.
ShowDelay int? null The wait in ms before the placeholder appears, so a fast response never flashes one. Pure CSS, so it also works under static SSR.
Size BitSize? null The default line height and circle diameter. An explicit Height or Width wins over it.
Stagger int? null The offset in ms between the animations of consecutive lines: line n starts at Delay + n * Stagger.
Styles BitShimmerClassStyles? null Custom CSS styles for different parts of the BitShimmer.
Template RenderFragment? null A custom skeleton built from shimmers of its own, replacing the default placeholder. ShowDelay still holds it back as one.
Width string? null The width of the shimmer. Unlike Height it stays after the swap, so the placeholder and the content share a column.

BitComponentBase parameters

Name Type Default value Description
AriaLabel string? null Gets or sets the accessible label for the component, used by assistive technologies.
Class string? null Gets or sets the CSS class name(s) to apply to the rendered element.
Dir BitDir? null Gets or sets the text directionality for the component's content.
Disabled bool false Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction.
ForceAnimation bool false Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes Dictionary<string, object> new Dictionary<string, object>() Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters.
Id string? null Gets or sets the unique identifier for the component's root element.
Style string? null Gets or sets the CSS style string to apply to the rendered element.
TabIndex string? null Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility BitVisibility BitVisibility.Visible Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name Type Default value Description
UniqueId Guid Guid.NewGuid() Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement ElementReference Gets the reference to the root HTML element associated with this component.

BitShimmerClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitShimmer.
Content string? null Custom CSS classes/styles for the content of the BitShimmer. The same box holds the content an Overlay covers.
Label string? null Custom CSS classes/styles for the live region of the BitShimmer that carries its Label and LoadedLabel. It is rendered right after the root, not inside it, so a shimmer hidden by a stylesheet hides the region through these as well.
ShimmerWrapper string? null Custom CSS classes/styles for the shimmer wrapper of the BitShimmer. A multi-line shimmer draws one wrapper per line, so these are applied to each of them.
Shimmer string? null Custom CSS classes/styles for the shimmer of the BitShimmer, which is the animated part inside each wrapper and is not drawn at all when the animation is None.

BitShimmerAnimation enum

Name Value Description
Wave 0 A highlight band sweeps across the placeholder from one side to the other, reversing with the direction of the page.
Pulse 1 The placeholder breathes between full and reduced opacity, which is cheaper to paint than the wave and calmer on a page full of placeholders.
Fade 2 The placeholder fades all the way out and back in, a heavier version of the pulse for a single placeholder that has to be noticed.
None 3 No animation at all: the placeholder is a static block of its Background, with no animated part left for Color to paint.

BitShape enum

Name Value Description
Rounded 0 The corner radius the current theme gives to this kind of surface.
Square 1 Sharp corners with no radius at all.
Pill 2 Fully rounded ends: a pill where the box is wider than it is tall, and a circle where the box is square.
Circle 3 A true circle, which takes its diameter from whichever of the height and the width is set.

BitSize enum

Name Value Description
Small 0 The small size shimmer.
Medium 1 The medium size shimmer.
Large 2 The large size shimmer.

BitPoliteness enum

Name Value Description
Off 0 The region is not a live region: nothing in it is announced as it changes.
Polite 1 The change waits its turn and is announced once the screen reader has finished what it was saying.
Assertive 2 The change interrupts the screen reader and is announced right away.

BitColor enum

Name Value Description
Primary 0 Info Primary general color.
Secondary 1 Secondary general color.
Tertiary 2 Tertiary general color.
Info 3 Info general color.
Success 4 Success general color.
Warning 5 Warning general color.
SevereWarning 6 SevereWarning general color.
Error 7 Error general color.
PrimaryBackground 8 Primary background color.
SecondaryBackground 9 Secondary background color.
TertiaryBackground 10 Tertiary background color.
PrimaryForeground 11 Primary foreground color.
SecondaryForeground 12 Secondary foreground color.
TertiaryForeground 13 Tertiary foreground color.
PrimaryBorder 14 Primary border color.
SecondaryBorder 15 Secondary border color.
TertiaryBorder 16 Tertiary border color.

BitVisibility enum

Name Value Description
Visible 0 The content of the component is visible.
Hidden 1 The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed 2 The component is hidden (display:none).

BitDir enum

Name Value Description
Ltr 0 Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl 1 Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto 2 Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.