Backdrop

A full-screen semi-transparent overlay with content slot, color/opacity/blur customization, fade in/out animation and lifecycle events; the node is automatically unmounted after the exit animation finishes when open=false, leaving no orphan DOM.

Basic usage

Basic usage

Open backdrop

Click anywhere on the backdrop to close it (listen for oas-click).

Example

Content slot (full-screen loading)

Content slot (full-screen loading)

Full-screen loading

The default slot hosts content above the mask (spinner / text / onboarding, centered); clicking the content area does NOT fire oas-click — only clicking the mask itself closes.

Example

Color & opacity

Color & opacity

Dark maskLight maskThemed mask

color accepts any CSS color or one of the 11 preset names; opacity supports thin (0.35) / default (0.55) / thick (0.75) levels or a 0-1 number. Theme-level overrides via --oas-backdrop-bg / --oas-backdrop-opacity variables.

Example

Full-value blur

Full-value blur

Strong blur + saturationDefault blur

blur with an empty value falls back to blur(4px) (backward compatible); a string accepts any CSS backdrop-filter value.

Example

Fade animation & lifecycle events

Fade animation & lifecycle events

Open (watch the fade)

Open/close plays an opacity fade (transform/opacity only); oas-after-show / oas-after-close fire when the transition finishes; skipped under prefers-reduced-motion.

Example

Persistent (non-dismissible) backdrop

Persistent (non-dismissible) backdrop

Open persistent backdrop

persistent blocks mask-click dismissal (no oas-click is fired); clicking the mask shakes the content to hint it cannot be dismissed — close via the content button or the host. The keyboard/SR close channel (focus the "Close backdrop" button at the top with Tab, label via close-label) works as well.

Example

Click propagation control

Click propagation control

Open (click passes through)

stop-propagation blocks mask clicks from reaching the host document by default (the mask's job is to block background interactions); set it to false to let mask clicks continue to page-level click listeners.

Example

Transparent & blur

Transparent & blur

Transparent + blurFully transparent

Example

No scroll lock

No scroll lock

Open (scrollable)

lock-scroll defaults to true; set it to false to keep the body scrollable.

Example

API

oas-backdrop

Attributes

Attribute	Description	Type	Default
blur	Blur the background	—	—
close-label	aria-label of the screen-reader close button (sr-only by default, revealed on Tab focus so keyboard users can close the overlay); falls back to the locale modal.close	—	—
color	Overlay background color: any CSS color value, or one of the 11 preset names (magenta/red/volcano/orange/gold/lime/green/cyan/blue/geekblue/purple, mapped to --oas-preset-* tokens); falls back to --oas-backdrop-bg when unset	—	—
lock-scroll	Lock body scroll while open	string	true
opacity	Overlay opacity: levels thin (0.35) / default (0.55) / thick (0.75) or a 0–1 number; applies to the scrim layer only (does not dim overlay content); invalid values fall back to --oas-backdrop-opacity	—	—
open	Whether shown	boolean	—
persistent	Persistent overlay: mask clicks do not emit oas-click (host-driven closing stops working); the content shakes instead as a not-closable hint	boolean	—
stop-propagation	Stop mask clicks from propagating into the host document (default true; "false" allows bubbling)	string	true
transparent	Transparent overlay (no background)	—	—

Events

Event	Description
oas-after-close	Emitted after the close animation finishes (canonical, aligned with the after-* family); no detail. Scroll unlock has already happened before this; node removal (the element removes itself) happens after this
oas-after-show	Emitted after the enter animation finishes (canonical, aligned with the after-* family); no detail; emitted immediately under reduced motion
oas-click	Backdrop clicked, detail.originalEvent is the original click event

Slots

Name	Description
default	Backdrop content

CSS Variables

CSS Variable	Default
--oas-backdrop-bg	var(--oas-color-overlay)
--oas-backdrop-blur	none
--oas-backdrop-opacity	1

• No focus trap of its own (handled by the overlying dialog); Esc does not auto-close (decided by the outer dialog).
• The node is removed from the DOM after the exit animation when open=false, leaving no orphan DOM; when multiple backdrops coexist, scroll is restored only when the last one closes.
• Click targeting: only clicks on the mask itself fire oas-click (content-area clicks do not); stop-propagation blocks mask clicks from reaching the host document by default.