Limited support Use with care and confirm browser support before shipping it to all users.

overlay

Experimental: This is an experimental technology

Check the Browser compatibility table carefully before using this in production.

The overlay CSS property specifies whether an element appearing in the top layer (for example, a shown popover or modal <dialog> element) is actually rendered in the top layer. This property is only relevant within a list of transition-property values, and only if allow-discrete is set as the transition-behavior.

It is important to note that overlay can only be set by the browser — author styles cannot change the overlay value of any element. You can, however, add overlay to the list of transition properties set on an element. This causes its removal from the top layer to be deferred so it can be animated instead of disappearing immediately.

Note: When transitioning overlay, you need to set transition-behavior: allow-discrete on the transition so that it will animate. overlay animations differ from normal discrete animations in that the visible (i.e., auto) state will always be shown for the full duration of the transition, regardless of whether it is the start or end state.

Syntax and cascadeVisual styling

Browser support

Feature Desktop Mobile
Chrome
Edge
Firefox
Safari
Chrome Android
Safari iOS
overlay
Experimental
117
117
117
auto
Experimental
117
117
117
none
Experimental
117
117
117
1+Supported (version) Not supported ※Has note Sub-feature descriptions sourced from MDN Web Docs (CC BY-SA 2.5)

Syntax

CSS 
dialog {
  transition: opacity 0.3s, overlay 0.3s allow-discrete;
}
dialog:not([open]) {
  opacity: 0;
}

Live demo

dialogdisplay

CSS dialogdisplay demo.

PreviewFullscreen

fade out

CSS fade out demo.

PreviewFullscreen

hidden

CSS hidden demo.

PreviewFullscreen

Use cases

  • Use overlay

    Use overlay when the default CSS behavior is not expressive enough for the component or layout you are building.

  • Handle edge cases

    Apply overlay to solve a specific styling constraint without introducing broader layout or behavior changes.

Cautions

  • Test overlay in the browsers you support, especially if it changes layout, text handling, or interaction behavior.
  • Plan a fallback or acceptable degradation path when support is still limited.

Accessibility

  • Confirm that using overlay does not make content harder to perceive, understand, or operate in assistive contexts.

Related links