Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท Positioning and Stacking

The top layer

Concept reference for the CSS top layer: which elements enter it, why z-index and overflow no longer matter for them, how ::backdrop works, and how to animate.

The top layer is a special rendering layer that sits above everything else on the page, above every stacking context and above any z-index value you can write. Elements that the browser places in it are painted last, on top of the rest of the document, no matter where they sit in the HTML.

It exists to solve a very old problem: menus, dialogs and tooltips that had to escape clipped parents and fight over z-index numbers. Today you do not enter the top layer with CSS. You enter it with HTML and JavaScript features, and the browser does the rest.

HTML
<button popovertarget="tip">Show tip</button>
<div id="tip" popover>I am in the top layer while open.</div>

What goes into the top layer

Feature How it enters
Modal <dialog> dialog.showModal()
Popover An element with the popover attribute, while it is open (showPopover() or a popovertarget button)
Fullscreen element element.requestFullscreen()

A plain <dialog open> or dialog.show() is not in the top layer. Only showModal() is.

Try it

A popover escapes a clipping parent
A modal dialog beats any z-index

How it works

  • Painting order. Top-layer elements are drawn above the whole document. Among themselves, the one that entered the top layer last is on top. Opening a second popover or dialog puts it above the first.
  • z-index does not apply. You cannot raise or lower an element inside the top layer with z-index. The order comes only from when each element was added.
  • No clipping by ancestors. An element in the top layer is rendered as if it were a child of the viewport. overflow: hidden, clip-path and similar properties on its ancestors do not clip it, and transform on an ancestor does not change what it is positioned against.
  • Inheritance is unchanged. The DOM tree is the same. The element still inherits properties such as color and font-family from its real parent, and events still bubble through it.
  • Default positioning. The browser's style sheet gives top-layer elements position: fixed (modal dialogs and popovers). Popovers and dialogs are centered by default using inset: 0 and margin: auto. You can override them.
  • Backdrop. A modal dialog, a fullscreen element and a popover each get a ::backdrop pseudo-element, painted directly under the element. Style it to dim the page. A popover's backdrop is transparent by default.

Animating entry and exit

Elements enter the top layer by changing from display: none to a displayed state, and they leave it the same way. To animate that you need three tools together:

CSS
dialog {
  opacity: 0;
  transition: opacity 0.25s, overlay 0.25s allow-discrete, display 0.25s allow-discrete;
}
dialog[open] { opacity: 1; }

@starting-style {
  dialog[open] { opacity: 0; }
}
  • @starting-style gives the element a "before" state for the first frame.
  • transition-behavior: allow-discrete (or the allow-discrete keyword in the transition shorthand) lets display change at the end of the exit transition.
  • The overlay property (none or auto) is controlled by the browser. Transitioning it with allow-discrete keeps the element in the top layer until the exit animation has finished. Check support before relying on it.

Usage notes

  • Prefer popover and <dialog> over hand-rolled position: fixed overlays. You get focus handling, Esc to close and light dismiss without writing any of it.
  • A modal dialog makes the rest of the page inert: it cannot be focused or clicked. A non-modal popover does not.
  • Use :modal and :popover-open to style the state.
  • Do not stack a custom z-index fight on top of it. If something appears above your dialog, it is usually another top-layer element opened later.
  • Top-layer elements are removed from the top layer when they are removed from the document or closed.

Browser support

<dialog> with showModal() and the Fullscreen API are supported in every current browser, and the popover attribute is supported in the current versions of Chrome, Edge, Firefox and Safari. Animating exit with overlay and allow-discrete is newer and not available in every browser, so treat the animation as an enhancement.