Backdrop

Custom overlay content

Same controlled shape as Modal/Drawer — isOpen and onClose are both required, and children is whatever you want rendered above the dimmed backdrop, with total control over its layout instead of Modal's fixed header/body/footer slots.

function ImageLightbox({ src, isOpen, onClose }: { src: string; isOpen: boolean; onClose: () => void }) {
  return (
    <Backdrop isOpen={isOpen} onClose={onClose} blur="lg">
      <img src={src} alt="" className="max-h-[90vh] max-w-[90vw] rounded-lg" />
    </Backdrop>
  );
}

Blur, tint, and opacity

blur accepts true (a sensible default), a size token, or a raw pixel number for the backdrop-filter blur amount. backgroundColor and backgroundOpacity control the dim layer's tint independently of the blur, for anything from a near-black scrim to a subtle, barely-there overlay.

<Backdrop isOpen={isOpen} onClose={onClose} blur="sm" backgroundOpacity={60}>
  {content}
</Backdrop>

Entrance animation

animationType picks how the backdrop and its content enter/exit (fade, zoom, or a directional slide), with animationDuration/easing to fine-tune the feel — the same animation system Modal and Drawer forward their own animation props into internally.

<Backdrop isOpen={isOpen} onClose={onClose} animationType="zoom" animationDuration={0.2}>
  {content}
</Backdrop>

Full-size content

By default the content wrapper sizes to its content and centers within the backdrop. Set contentFullSize to stretch it to fill the backdrop instead — useful for a custom overlay that needs to manage its own internal layout/scrolling edge to edge, like a full-viewport image gallery.

Accessibility

• Traps focus inside children while open and restores it to whatever triggered the backdrop on close, the same focus-trap behavior Modal and Drawer inherit from it.
• lockScroll (on by default) prevents the page behind the backdrop from scrolling while it's open, keeping the user's context stable.
• closeOnEscape and closeOnOutsideClick (both on by default) give keyboard and mouse users independent, standard ways to dismiss the overlay without you having to wire either up manually.

Props reference

All available props for Backdrop. See the full component page for an interactive playground.

Best practices

• ◆Reach for Modal or Drawer first — they're Backdrop plus a well-tested header/body/footer layout. Drop to Backdrop directly only when your content genuinely doesn't fit that shape (a lightbox, a custom full-screen takeover).
• ◆Keep trapFocus on unless you have a specific reason to disable it — turning it off means keyboard focus can silently leave the overlay while it's still open, which is rarely what you want.
• ◆Use contentFullSize sparingly — most overlay content reads better centered and sized to itself; full-size is for genuinely edge-to-edge experiences, not a way to avoid sizing your content properly.
• ◆When building a custom overlay on Backdrop, keep an explicit dismiss control inside children too (not just Escape/outside-click) — a fully custom layout can otherwise leave touch or assistive-tech users without an obvious way to close it.