Overlay
Last Updated: September 2026Overlays are a visual blocker that occludes content behind it in order to get the user to focus on whats above it.
Source CodeAnatomy
link- 1Backdrop
Variants
linkAbsolute
Default. Fills the nearest positioned ancestor.
With blur
blur softens content behind the dimmer.
Fixed
position="fixed" covers the viewport — usually mounted by the app shell.
Usage Guidelines
linkWhen to use
- •As the dimmed backdrop behind custom dialogs or takeovers.
- •When you need the same surface Modal uses, without the dialog chrome.
- •To temporarily de-emphasize page content under floating UI.
When not to use
- •When you need a full dialog — use Modal (it already includes Overlay).
- •For anchored tips — use Popover or Tooltip.
- •As a standalone page background treatment.
Place absolute Overlay inside a positioned parent.
Don't use absolute Overlay without a positioned ancestor — it won't cover what you expect.
Prefer Modal/Drawer when you need dialog behavior — they own the backdrop.
Don't stack a manual Overlay on top of Modal's own backdrop.
Behaviors
linkPresentational only
- •Overlay does not manage open state — parents mount/unmount or toggle it.
- •It does not trap focus or provide dialog semantics.
Positioning
- •absolute (default) fills a relative/absolute/fixed parent.
- •fixed covers the viewport and uses the modal z-index token.
Content Guidelines
linkUsage
- •Keep Overlay free of text — content belongs in the dialog above it.
- •Use blur sparingly when readability behind the dimmer matters less.
Accessibility
linkText & Labels
- •Overlay is decorative; the dialog above it must provide the accessible name.
ARIA attributes
- •Prefer Modal/Drawer for accessible modal behavior rather than Overlay alone.
Keyboard Support
- •Overlay itself is not focusable — keyboard handling belongs on the dialog layer.
WCAG Compliance Standards
FAQs
linkDoes Overlay open and close itself?
No. It is presentational. Mount it when you need a backdrop, or use Modal/Drawer which include one.
When do I use blur?
When you want to further de-emphasize content behind the dimmer. Default is a flat scrim without blur.
Why isn't my absolute Overlay covering the card?
The parent needs position: relative (or absolute/fixed) and usually overflow handling.