Stacking Layers

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

The tier decides between kinds of layers. An overlay always paints above a float, no matter which one opened first.
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

Tier	z-index	Layers	Renders into
Page chrome	`z-50`	Sandbar, AlertCenter banners, sticky headers	In place, in the page's own stacking context
Float	`z-50`	Popover, Tooltip, Select, DropdownMenu, HoverCard	The nearest overlay's positioner, else `document.body`
Overlay	`z-60`	Dialog, AlertDialog, Sheet, Command's palette	The nearest overlay's positioner, else `document.body`
Toast	`999999999`	Toast (sonner's own viewport)	In place where `<Toaster />` renders; painted above both tiers
Skip link	`z-max`	SkipToMainLink	In 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 doubles as the overlay's layer container: floats composed inside the overlay portal into it, after the content, so they paint above the content inside the overlay's own stacking context. The positioner is a styling hook:

Overlay	Positioner slot
`Dialog`	`data-slot="dialog-positioner"`
`AlertDialog`	`data-slot="alert-dialog-positioner"`
`Sheet`	`data-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. Before this contract, every layer shared z-50 and mount order alone decided, so a popover that opened late (an onboarding popover after hydration, for example) painted on top of 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.

See the contract work

Every rule above has a live permutation below, and each also has an automated twin in mantle's layering test matrix (layer-container.test.tsx pins DOM placement; layer-container.browser.test.tsx proves paint order with real hit-testing).

A base float never paints above an overlay

The bug shape the overlay tier exists for: 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, and it waits on the page when the dialog closes.

1import { Button } from "@ngrok/mantle/button";2import { Dialog } from "@ngrok/mantle/dialog";3import { Popover } from "@ngrok/mantle/popover";4import { useState } from "react";5 6export function LateAnnouncementDemo() {⋯7	const [announcementOpen, setAnnouncementOpen] = useState(false);8 9	return (10		<div className="flex flex-wrap items-center gap-4">⋯11			<Popover.Root open={announcementOpen} onOpenChange={setAnnouncementOpen}>⋯12				<Popover.Anchor asChild>⋯13					<Button⋯14						type="button"15						appearance="outlined"16						intent="neutral"17						onClick={() => setAnnouncementOpen(true)}18					>19						Show announcement20					</Button>21				</Popover.Anchor>22				<Popover.Content⋯23					// A click anywhere else must not dismiss the announcement — only24					// its own button does, like a real onboarding popover.25					onInteractOutside={(event) => {⋯26						event.preventDefault();27					}}28					side="bottom"29					className="flex flex-col gap-2"30				>31					<p className="text-strong text-sm font-medium">Your account moved down here</p>32					<Popover.Close asChild>⋯33						<Button type="button" appearance="filled" intent="neutral" size="sm">⋯34							Got it35						</Button>36					</Popover.Close>37				</Popover.Content>38			</Popover.Root>39			<Dialog.Root>⋯40				<Dialog.Trigger asChild>⋯41					<Button type="button" appearance="filled" intent="neutral">⋯42						Open takeover43					</Button>44				</Dialog.Trigger>45				<Dialog.Content appearance="full-page">⋯46					<Dialog.Header>⋯47						<Dialog.Title>Takeover</Dialog.Title>48						<Dialog.CloseIconButton />49					</Dialog.Header>50					<Dialog.Body className="space-y-4">⋯51						<p>⋯52							This button opens the page-level announcement popover while the dialog is on top — the53							way an onboarding popover opens on its own after hydration.54						</p>55						<Button⋯56							type="button"57							appearance="outlined"58							intent="neutral"59							onClick={() => setAnnouncementOpen(true)}60						>61							Trigger the late announcement62						</Button>63						<p>⋯64							The announcement stays under this dialog because it belongs to the page, not to the65							dialog. Close the dialog to find it waiting where it belongs.66						</p>67					</Dialog.Body>68				</Dialog.Content>69			</Dialog.Root>70		</div>71	);72}

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.

1<Dialog.Root>⋯2	<Dialog.Trigger asChild>⋯3		<Button type="button" appearance="filled" intent="neutral">⋯4			Open dialog5		</Button>6	</Dialog.Trigger>7	<Dialog.Content>⋯8		<Dialog.Header>⋯9			<Dialog.Title>Floats in a dialog</Dialog.Title>10			<Dialog.CloseIconButton />11		</Dialog.Header>12		<Dialog.Body className="space-y-4">⋯13			<Popover.Root>⋯14				<Popover.Trigger asChild>⋯15					<Button type="button" appearance="outlined" intent="neutral">⋯16						Open popover17					</Button>18				</Popover.Trigger>19				<Popover.Content>⋯20					<p>This popover paints above the dialog that owns it.</p>21				</Popover.Content>22			</Popover.Root>23			<Select.Root>⋯24				<Select.Trigger className="w-45">⋯25					<Select.Value placeholder="Open select" />26				</Select.Trigger>27				<Select.Content>⋯28					<Select.Item value="apple">Apple</Select.Item>29					<Select.Item value="banana">Banana</Select.Item>30				</Select.Content>31			</Select.Root>32			<DropdownMenu.Root>⋯33				<DropdownMenu.Trigger asChild>⋯34					<Button type="button" appearance="outlined" intent="neutral">⋯35						Open menu36					</Button>37				</DropdownMenu.Trigger>38				<DropdownMenu.Content>⋯39					<DropdownMenu.Item>Menu item</DropdownMenu.Item>40				</DropdownMenu.Content>41			</DropdownMenu.Root>42			<Tooltip.Root>⋯43				<Tooltip.Trigger asChild>⋯44					<Button type="button" appearance="outlined" intent="neutral">⋯45						Hover for a tooltip46					</Button>47				</Tooltip.Trigger>48				<Tooltip.Content>This tooltip paints above the dialog.</Tooltip.Content>49			</Tooltip.Root>50		</Dialog.Body>51	</Dialog.Content>52</Dialog.Root>

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.

1<Sheet.Root>⋯2	<Sheet.Trigger asChild>⋯3		<Button type="button" appearance="filled" intent="neutral">⋯4			Open sheet5		</Button>6	</Sheet.Trigger>7	<Sheet.Content>⋯8		<Sheet.Header>⋯9			<Sheet.TitleGroup>⋯10				<Sheet.Title>Pickers in a sheet</Sheet.Title>11				<Sheet.Actions>⋯12					<Sheet.CloseIconButton />13				</Sheet.Actions>14			</Sheet.TitleGroup>15		</Sheet.Header>16		<Sheet.Body className="space-y-4">⋯17			<Combobox.Root>⋯18				<Combobox.Input placeholder="Search fruits..." />19				<Combobox.Content>⋯20					<Combobox.Item value="Apple" />21					<Combobox.Item value="Banana" />22					<Combobox.Item value="Cherry" />23				</Combobox.Content>24			</Combobox.Root>25			<MultiSelect.Root>⋯26				<MultiSelect.Trigger>⋯27					<MultiSelect.TagValues />28					<MultiSelect.Input placeholder="Select fruits..." />29				</MultiSelect.Trigger>30				<MultiSelect.Content>⋯31					<MultiSelect.Item value="apple">Apple</MultiSelect.Item>32					<MultiSelect.Item value="banana">Banana</MultiSelect.Item>33				</MultiSelect.Content>34			</MultiSelect.Root>35		</Sheet.Body>36	</Sheet.Content>37</Sheet.Root>

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.

1<Popover.Root>⋯2	<Popover.Trigger asChild>⋯3		<Button type="button" appearance="filled" intent="neutral">⋯4			Open popover5		</Button>6	</Popover.Trigger>7	<Popover.Content className="space-y-2">⋯8		<p>Open the select — it paints above this popover.</p>9		<Select.Root>⋯10			<Select.Trigger className="w-45">⋯11				<Select.Value placeholder="Open select" />12			</Select.Trigger>13			<Select.Content>⋯14				<Select.Item value="apple">Apple</Select.Item>15				<Select.Item value="banana">Banana</Select.Item>16			</Select.Content>17		</Select.Root>18	</Popover.Content>19</Popover.Root>

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.

1<Dialog.Root>⋯2	<Dialog.Trigger asChild>⋯3		<Button type="button" appearance="filled" intent="neutral">⋯4			Open dialog5		</Button>6	</Dialog.Trigger>7	<Dialog.Content>⋯8		<Dialog.Header>⋯9			<Dialog.Title>First overlay</Dialog.Title>10			<Dialog.CloseIconButton />11		</Dialog.Header>12		<Dialog.Body>⋯13			<Sheet.Root>⋯14				<Sheet.Trigger asChild>⋯15					<Button type="button" appearance="outlined" intent="neutral">⋯16						Open a sheet over this dialog17					</Button>18				</Sheet.Trigger>19				<Sheet.Content>⋯20					<Sheet.Header>⋯21						<Sheet.TitleGroup>⋯22							<Sheet.Title>Second overlay</Sheet.Title>23							<Sheet.Actions>⋯24								<Sheet.CloseIconButton />25							</Sheet.Actions>26						</Sheet.TitleGroup>27					</Sheet.Header>28					<Sheet.Body>⋯29						<Popover.Root>⋯30							<Popover.Trigger asChild>⋯31								<Button type="button" appearance="outlined" intent="neutral">⋯32									Open a popover over the sheet33								</Button>34							</Popover.Trigger>35							<Popover.Content>⋯36								<p>Dialog, then sheet, then this popover — each paints above the last.</p>37							</Popover.Content>38						</Popover.Root>39					</Sheet.Body>40				</Sheet.Content>41			</Sheet.Root>42		</Dialog.Body>43	</Dialog.Content>44</Dialog.Root>

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.

1<Dialog.Root>⋯2	<Dialog.Trigger asChild>⋯3		<Button type="button" appearance="filled" intent="neutral">⋯4			Open dialog5		</Button>6	</Dialog.Trigger>7	<Dialog.Content>⋯8		<Dialog.Header>⋯9			<Dialog.Title>Toast from a dialog</Dialog.Title>10			<Dialog.CloseIconButton />11		</Dialog.Header>12		<Dialog.Body>⋯13			<Button⋯14				type="button"15				appearance="outlined"16				intent="neutral"17				onClick={() => {⋯18					makeToast(19						<Toast.Root intent="success">⋯20							<Toast.Icon />21							<Toast.Message>This toast paints above the dialog.</Toast.Message>22						</Toast.Root>,23					);24				}}25			>26				Fire a toast27			</Button>28		</Dialog.Body>29	</Dialog.Content>30</Dialog.Root>

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, which is almost always correct.
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. Reach for this rarely: above the overlay tier, only toasts and the skip link should live.
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 full rationale, the alternatives considered, and the paint-order test matrix live in the repo's decision doc, decisions/2026-08-11-floating-layer-tiers.md.