Prototype Library

Loading Overlay

Covers its positioned parent with a centered spinner and optional message while a region is busy. Opaque or semi-transparent backdrop.

Inherited .astro import EsaLoadingOverlay from '@esa/ecology/esa-loading-overlay.astro';

Preview

Place the overlay inside a position: relative container; its absolute backdrop fills the parent.

Underlying content that is being covered while loading.

<div style="position: relative; min-height: 180px;">
  <p>Underlying content being covered.</p>
  <LoadingOverlay active={true} message="Loading data…" />
</div>

States

A transparent backdrop lets the content show through faintly. When active is false the overlay renders nothing.

You can still see this content faintly through the overlay.

Inactive — the overlay renders nothing.

<LoadingOverlay active={true} transparent={true} message="Saving…" />
<LoadingOverlay active={false} />

API

PropTypeDefaultDescription
active boolean false When false the overlay renders nothing.
message string — Optional caption shown under the spinner.
transparent boolean false Semi-transparent backdrop instead of an opaque one.

Accessibility

  • The backdrop is a single named graphic — role="img" with message as its accessible name, plus aria-busy — and the visual content inside it is aria-hidden so the name is not read twice. It is not a role="status" live region: this page said so until 2026-08-18 and the source had already moved off it, because a region created in the same tick as its text does not announce.
  • The backdrop sits at z-index: 10 over the parent and intercepts pointer interaction while active.
  • It does not stop the keyboard, and it cannot. The overlay is position: absolute, scoped to its nearest positioned ancestor — so a keyboard user can still Tab into controls sitting under an opaque backdrop, and the component cannot make that region inert because it does not own it. Making the covered region inert while loading is the call site's job.
  • For long operations, consider moving focus or announcing the busy state at the call site.