`. The `z-1` through `z-4` utilities are Tailwind v4, where any integer works. On v3 you would write `z-[1]` or extend the scale. The exported constants matter more than they look. They're the actual API. Nobody writes `"stacked-layer-2"` as a string; they import `STACKED_LAYER_2`, which makes the set of layers greppable and renaming one a find-references job rather than an archaeology problem. It's convention, not enforcement: the provider takes `id: string`, so a typo still compiles and quietly falls back to the body. Typing that prop as a union of the four constants would close the gap, and I haven't bothered. Now the part that makes it work, in the root layout: ```tsx {3,6} title="app/layout.tsx" showLineNumbers {/* ... theme script ... */}

{children}

``` `#_next` is `relative z-0`. That single pair of properties creates a stacking context around the entire application, and it's the most important line in this whole post. **Every `z-index` written anywhere inside the app is now scoped to that context.** Someone can write `z-index: 999999` in a component and it will still paint below `stacked-layer-1`, because it isn't competing with the layers. It's competing with its siblings, inside a box that itself sits at `z-0`. ![Two scales, not one](https://tkhquang.dev/uploads/images/blog/stacked-layers-stacking-context.svg) That's the difference between a convention and a guarantee. You're no longer asking people to use small numbers. You've made large numbers local. ## Routing portals into a layer The layers are just holes in the DOM. Something has to point portals at them. This blog uses [Ariakit](https://ariakit.org/), whose `Portal` component reads its target from a `PortalContext`, so a provider is enough: ```tsx title="src/providers/StackedLayerProvider.tsx" showLineNumbers "use client"; import { PortalContext } from "@ariakit/react"; import React, { useEffect, useState } from "react"; interface StackedLayerProviderProps { children: React.ReactNode; id: string; } /** * Registers the portals of the children to the corresponding layer matching id * * NOTE: Always make sure to have the Zlayers exist in the HTML tree */ function StackedLayerProvider({ children, id }: StackedLayerProviderProps) { /** * Stays null until mounted: there is no document on the server. A null * PortalContext already resolves to document.body in Ariakit, so a missing * layer degrades instead of breaking. */ const [rootNode, setRootNode] = useState(null); useEffect(() => { setRootNode(document.getElementById(id)); }, [id]); return ( {children} ); } export default StackedLayerProvider; ``` That's a lot shorter than what it replaced. Here is the version it grew out of, comments and all. The import says Ariakit because that got updated during the migration, but the shape of it dates from [Reakit](https://github.com/ariakit/ariakit/tree/reakit), which is what Ariakit was called before the rename: ```tsx title="src/providers/StackedLayerProvider.tsx, before" import { PortalContext } from "@ariakit/react"; import React, { useEffect, useState } from "react"; interface StackedLayerProviderProps { children: React.ReactNode; id: string; } /** * Waits for Element to appears in DOM and returns it * @param id {string} * @returns Element */ const getElementByIdAsync = (id: string): Promise => new Promise((resolve) => { const getElement = () => { const element = document.getElementById(id); if (element) { resolve(element); } else { requestAnimationFrame(getElement); } }; getElement(); }); /** * Registers the portals of the children to the corresponding layer matching id */ function StackedLayerProvider({ children, id }: StackedLayerProviderProps) { // Set null to avoid rendering on SSR const [rootNode, setRootNode] = useState(null); useEffect(() => { setRootNode(document.body); (async () => { /** * This ensures the portals will be put into the correct layers * after the layers are mounted as it will wait for the root node * to appear in the HTML tree. * NOTE: Always make sure to have the Zlayers exist in the HTML tree */ const rootNode = await getElementByIdAsync(id); setRootNode(rootNode); })(); }, [id]); return ( {children} ); } export default StackedLayerProvider; ``` Two things in there look like overengineering now. Neither was. **The body fallback was free.** Reakit created its portal host node once and moved it: ```tsx title="reakit/src/Portal/Portal.tsx" const [hostNode] = React.useState(() => { if (canUseDOM) { const element = document.createElement("div"); element.className = Portal.__className; return element; } return null; }); useIsomorphicEffect(() => { if (!hostNode || !context) return undefined; context.appendChild(hostNode); return () => { context.removeChild(hostNode); }; }, [hostNode, context]); ``` `createPortal` targets `hostNode`, and `hostNode` never changes identity. Flipping the context from body to layer relocates one `div` and leaves React's tree untouched. Ariakit builds its portal element inside the effect instead, so with no `portalElement` prop it calls `createElement("div")` on every run, with `context` in the deps. A new container means `createPortal` gets a new target, so a portal mounted while the context flips gets unmounted and remounted. Same three lines of our code, different cost. **The polling was necessary.** In the codebase this came from, the layers were mounted by a client-side container component, so the slot really might not exist yet when the provider looked for it. Here they're static markup in the root layout, visible before a line of client JavaScript runs: ```bash $ curl -s localhost:3000/blog | grep -o 'id="stacked-layer-[0-9]"[^>]*' id="stacked-layer-1" class="relative z-1" id="stacked-layer-2" class="relative z-2" id="stacked-layer-3" class="relative z-3" id="stacked-layer-4" class="relative z-4" ``` That's what makes the lookup safe. Not "React commits everything before effects run", which streaming and selective hydration make untrue, but that these particular elements are in the server response before React is involved at all. One `getElementById` can't miss them. So both lines went, for different reasons. The polling because its premise expired. The body fallback because it never bought anything under either library: Reakit's `PortalContext` defaulted to `getBodyElement()` and read as `useContext(PortalContext) || getBodyElement()`, Ariakit defaults to `null` and resolves it the same way. Setting the body yourself only repeats what a null context already does. I did go looking for that remount before believing in it, with a `MutationObserver` on `` installed before any page script, against `next build` output rather than the dev server. On the blog index, nothing: ```text title="portal mutations, /blog" ADD DIV#id-fucnoo -> stacked-layer-1 ``` The `div` is created inside the layer and never touches the body. That portal sits behind a `` boundary, so React hydrates it after the provider's effect has run, and it's never mounted while the context is still `null`. Then the same trace on a post page, which renders a second portal outside any boundary: ```text title="portal mutations, /blog/posts/..." ADD DIV#id-v2pi62 -> BODY DEL DIV#id-v2pi62 <- BODY ADD DIV#id-afbx9k -> stacked-layer-1 ADD DIV#id-jnuimh -> stacked-layer-1 ``` There it is. That portal's layout effect runs in the same commit as hydration, before the provider's passive effect, so it really does take the body for a beat and then get relocated. The remount is real. It just happens once at hydration with nothing open, which is why nobody has ever noticed. Worth knowing that "the layers are quiet" was a claim about one page, not the app. Which leaves the `NOTE` as the only thing between you and a missing layer: > NOTE: Always make sure to have the Zlayers exist in the HTML tree That's a hard requirement, not a hint. If the layers are gone, `getElementById` returns `null`, Ariakit falls back to the body, and you've earned the debugging session. Sixty frames of retry logic to be polite about someone deleting a `div` from the root layout isn't defence, it's more code to be wrong. ## Using it At the call site, the whole system disappears. You wrap a subtree in a provider and every Ariakit portal inside it that hasn't been given an explicit target of its own, however deeply nested, lands in the right layer: ```tsx showLineNumbers export default function SomethingThatFloats() { return ( {/* All of these end up inside #stacked-layer-2 */}

); } ``` That's the property we actually wanted. A component three levels down doesn't need to know about layers, doesn't need to import a constant, doesn't need to have a `container` prop threaded down to it. It portals like normal, and context decides where "normal" points. ## Where it doesn't save you I've seen this pattern oversold, so here is what it doesn't do. **The isolation has exits.** The `z-0` on `#_next` only contains what stays inside `#_next`. A portal that targets anything else is, by definition, no longer in that subtree, which is precisely the mechanism the layers rely on but cuts both ways: a stray portal appended straight to `document.body` competes in the root stacking context rather than the app's, so a high enough `z-index` on it clears all four slots. Landing after them in the DOM only wins ties. Above all of that sits the browser's [top layer](https://www.w3.org/TR/css-position-4/#document-top-layer), which no `z-index` reaches: a `