overlay

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The overlay <dialog> element) is actually rendered in the top layer. This property is only relevant within a list of 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 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

css

/* Keyword values */
overlay: auto;
overlay: none;

/* Global values */
overlay: inherit;
overlay: initial;
overlay: revert;
overlay: revert-layer;
overlay: unset;

Values

auto: The element is rendered in the top layer if it is promoted to the top layer.
none: The element is not rendered in the top layer.

Formal definition

Animation type	Discrete behavior except when animating to or from `none` is visible for the entire duration

Formal syntax

overlay = 
  none  |
  auto

Examples

In this example, a transitions from hidden to shown and back again.

HTML

The HTML contains a popovertarget attribute.

html

<button popovertarget="mypopover">Show the popover</button>
<div popover="auto" id="mypopover">I'm a Popover! I should animate.</div>

CSS

The overlay property is only present in the list of transitioned properties. As overlay is a user-agent controlled property, it is not declared in the pre-transition or post-transition states.

css

html {
  font-family: "Helvetica", "Arial", sans-serif;
}

[popover]:popover-open {
  opacity: 1;
  transform: scaleX(1);
}

[popover] {
  font-size: 1.2rem;
  padding: 10px;

  /* Final state of the exit animation */
  opacity: 0;
  transform: scaleX(0);

  transition:
    opacity 0.7s,
    transform 0.7s,
    overlay 0.7s allow-discrete,
    display 0.7s allow-discrete;
  /* Equivalent to
  transition: all 0.7s allow-discrete; */
}

/* Needs to be included after the previous [popover]:popover-open
   rule to take effect, as the specificity is the same */
@starting-style {
  [popover]:popover-open {
    opacity: 0;
    transform: scaleX(0);
  }
}

/* Transition for the popover's backdrop */

[popover]::backdrop {
  background-color: transparent;
  transition:
    display 0.7s allow-discrete,
    overlay 0.7s allow-discrete,
    background-color 0.7s;
  /* Equivalent to
  transition: all 0.7s allow-discrete; */
}

[popover]:popover-open::backdrop {
  background-color: rgb(0 0 0 / 25%);
}

/* Nesting selectors (&) cannot represent pseudo-elements, so this 
   starting-style rule cannot be nested. */

@starting-style {
  [popover]:popover-open::backdrop {
    background-color: transparent;
  }
}

The two properties we want to animate are transition property to animate between the two.

Because the animated element is being promoted to the transition-behavior: allow-discrete value is also set in the shorthand to enable discrete transitions.

The following steps are also required to get the animation working in both directions:

A starting state for the animation is set inside the @starting-style at-rule. This is needed to avoid unexpected behavior. By default transitions are not triggered on elements' first style updates, or when the display type changes from none to another type. @starting-style allows you to override that default in a specific controlled fashion. Without this, the entry animation would not occur and the popover would just appear.
display is also added to the list of transitioned elements so that the animated element is visible (set to display: block) throughout both the entry and exit animation. Without this, the exit animation would not be visible; in effect, the popover would just disappear. Again, transition-behavior: allow-discrete is required in this case for the animation to occur.

You'll note that we've also included a transition on the ::backdrop that appears behind the popover when it opens, to provide a nice darkening animation. [popover]:popover-open::backdrop is needed to select the backdrop when the popover is open.

Result

The code renders as follows:

Note: Because popovers change from display: none to display: block each time they are shown, the popover transitions from its @starting-style styles to its [popover]:popover-open styles every time the entry transition occurs. When the popover closes, it transitions from its [popover]:popover-open state to the default [popover] state.

It is possible for the style transition on entry and exit to be different in such cases. See our Demonstration of when starting styles are used example for a proof of this.

Specifications

Specification
CSS Positioned Layout Module Level 4 # overlay

Browser compatibility

Help improve MDN

Learn how to contribute

This page was last modified on ⁨Nov 7, 2025⁩ by MDN contributors.

View this page on GitHub • Report a problem with this content