Shimmer Overlay
A sweeping highlight that plays over a loading surface.
ShimmerOverlay adds a moving sheen to a placeholder so a static skeleton reads
as actively loading rather than stalled. It fills its nearest positioned
ancestor, so give the parent relative and overflow-hidden.
<div className="relative h-16 w-60 overflow-hidden rounded-3 bg-bds-gray-10">
<ShimmerOverlay />
</div>The overlay is absolutely positioned and larger than its container, so the
overflow-hidden parent is what clips the sweep to the surface. The sheen
loops every 1.6s until you remove it, and it ignores pointer events, so
nothing underneath loses clicks. The animation lives in
@base-org/bds-web/styles.css; see Manual.
When to use
Use ShimmerOverlay on top of a skeleton surface so it reads as actively
loading rather than stalled.
Use something else when:
- You need the placeholder itself. Use Skeleton; the overlay only adds the sweep.
- The shape of the incoming content is unknown. Use Spinner.
Usage
Do
Layer it over a skeleton block whose corners you have already rounded — the
parent's overflow-hidden keeps the sheen inside that shape.
Don't
Place it over interactive content. It is a loading affordance, not decoration for something the reader can already use.
Props
ShimmerOverlay adds no props of its own and forwards any span props, such
as className, to its root. Its size and clipping come from the positioned,
overflow-hidden parent it fills.
Accessibility
ShimmerOverlay renders a purely decorative span marked aria-hidden, so it
is invisible to assistive technology. Convey the loading state on the region
itself — for example with role="status" — rather than relying on the shimmer.
When the reader prefers reduced motion, the sweep does not play.