Skip to main content

Stacking Layers

Every mantle surface that floats above the page stacks on one shared scale. Two rules decide what paints on top:

  1. The tier decides between kinds of layers. An overlay always paints above a float, no matter which one opened first.
  2. Ownership decides within a tier. A float composed inside an overlay portals into that overlay's positioner, so it paints above the overlay that owns it. Sibling layers in the same tier and container paint in mount order: the most recently mounted one wins.

The tiers

Tierz-indexLayersRenders into
Page chromez-50Sandbar, AlertCenter banners, sticky headersIn place, in the page's own stacking context
Floatz-50Popover, Tooltip, Select, DropdownMenu, HoverCardThe nearest overlay's positioner, else document.body
Overlayz-60Dialog, AlertDialog, Sheet, Command's paletteThe nearest overlay's positioner, else document.body
Toast999999999Toast (sonner's own viewport)In place where <Toaster /> renders; painted above both tiers
Skip linkz-maxSkipToMainLinkIn place; --z-index-max so nothing covers keyboard escape routes

Two components place themselves differently on purpose:

  • Combobox.Content renders in place at z-50: it does not portal, so the dialog primitive's Escape handling can see it.
  • MultiSelect.Content portals into the closest data-mantle-modal-content element (an enclosing overlay's content), else the nearest overlay's positioner, else document.body.

Layer containers

Each overlay renders a positioner: the fixed element that lays out its content. The positioner is also the overlay's layer container. A float composed inside the overlay portals into it after the content, so the float paints above the content, inside the overlay's own stacking context. Select the positioner by its data-slot:

OverlayPositioner slot
Dialogdata-slot="dialog-positioner"
AlertDialogdata-slot="alert-dialog-positioner"
Sheetdata-slot="sheet-positioner"

Ownership comes from composition, not timing. A float rendered inside Dialog.Content belongs to that dialog and paints above it. A float rendered outside stays at document.body and paints below every overlay, even when it opens later. Without the tiers, mount order alone would decide. A popover that opens late, such as an onboarding popover after hydration, would then paint over an open full-bleed dialog.

Floats do not register a container of their own. A select opened from inside a popover shares the popover's container and paints above the popover by mount order: the right rule for layers the user opened in sequence.

Escape follows the same order. While focus is in an overlay, Escape closes that overlay, even when a float outside it opened later. The float stays open under it.

An overlay yields to a frame above it that a script puts on <body>, such as a payment popup. While that frame is on top at the center of the viewport, the overlay lets it keep focus, and Escape moves focus into it. Third-party popups has the rule and an example.

See the contract work

Each example below shows one rule from this page.

A base float never paints above an overlay

The overlay tier exists for this case: an announcement popover opens on its own while a takeover dialog covers its anchor. Open the takeover, then trigger the late announcement from inside it: the announcement stays under the dialog. Press Escape to close the dialog, and the announcement waits on the page.

Floats inside a dialog paint above it

Each float composed inside the dialog portals into the dialog's positioner, so it opens on top of the dialog: never behind it, never clipped by it.

Pickers inside a sheet place themselves

Combobox.Content renders in place and MultiSelect.Content portals into the sheet's content element, so both open above the sheet and scroll with it.

Floats inside a float stack by mount order

A float does not register a layer container, so a select opened from a popover shares the popover's container and paints above the popover that spawned it.

Overlays stack in mount order

An overlay opened from inside another overlay portals into the outer overlay's positioner and paints above it, backdrop and all. The popover at the end of the chain paints above both.

Toasts clear every tier

A toast fired from inside an overlay renders in sonner's viewport, far above both tiers, so results stay visible no matter what is open.

Placing custom UI on the scale

  • Chrome that floats above page content but under overlays (a fixed action bar, a floating panel): use z-50 in the page, the same tier as page chrome. An open dialog covers it.
  • UI that must paint above open overlays: use z-60 and mount it after the overlay, or render it inside the overlay's content so it joins the overlay's layer. Use this rarely. Only toasts and the skip link belong above the overlay tier.
  • Never out-stack toasts. Toasts announce results of actions taken anywhere, including inside overlays.
  • Custom portals inside an overlay: pass the overlay's positioner as the portal target (query the data-slot above), or compose a mantle float, which resolves it automatically. Dialog.Portal and HoverCard.Portal accept a container prop when you need explicit control.
  • Do not select a float's portal as a direct body child (body > [data-radix-popper-content-wrapper]). Inside an overlay the float lives in the positioner. Target the float's data-slot instead.

The floating layer tiers decision doc has the full rationale, the alternatives, and the paint-order test matrix.