Overlays

Backdrop

Full-viewport fixed scrim primitive for custom overlay patterns such as loading dimmers and image lightboxes.

import { Backdrop } from '@lostgradient/cinder/backdrop';
overlayscrim
01

Overview

Full-viewport fixed scrim primitive for custom overlay patterns such as loading dimmers and image lightboxes.

Usage

svelte 
<script lang="ts">
  import { Backdrop } from '@lostgradient/cinder/backdrop';
</script>

Guidance

Use When

  • Providing a full-screen dimming layer behind a custom overlay that is not modal, drawer, or sheet.
  • Building a loading state that dims the full viewport while an async operation runs.

Avoid When

  • Interrupting the user for a decision — use modal or alert-dialog which manage focus and Escape automatically.
  • Showing a side panel — use drawer instead.
  • Showing structured content in a dialog — use modal, drawer, or sheet, which render their own native <dialog>::backdrop scrim.
Live preview
02

When to use

Use when
  • Providing a full-screen dimming layer behind a custom overlay that is not modal, drawer, or sheet.
  • Building a loading state that dims the full viewport while an async operation runs.
Avoid when
  • Interrupting the user for a decision — use modal or alert-dialog which manage focus and Escape automatically.
  • Showing a side panel — use drawer instead.
  • Showing structured content in a dialog — use modal, drawer, or sheet, which render their own native `<dialog>::backdrop` scrim.
03

Examples

Basic backdrop

A full-viewport scrim that dims content behind it. Click the backdrop to dismiss it.

04

Props

Props for backdrop
Name Type Default Required Bindable Description
open boolean req Whether the backdrop is visible and active.
invisible boolean false When true the backdrop is transparent but still captures pointer events, enabling click-to-close without dimming content behind it.
scrollLocked boolean true Lock body scroll while the backdrop is open (counted lock — safe to nest with other overlays). Set false when the consumer manages scrolling itself.
transitionDurationMilliseconds number Enter/leave animation duration in milliseconds. Collapses to 0 under prefers-reduced-motion. Overrides the default when provided.
onclick (event: MouseEvent) => void Click handler — use this to wire click-to-close on the scrim.
children snippet Optional content rendered above the scrim (e.g. a Spinner for a loading state).