From 51b8f0b72f59edb52466a15ad09594580f493453 Mon Sep 17 00:00:00 2001 From: Matt Rothenberg Date: Sat, 12 Sep 2026 14:01:44 -0400 Subject: [PATCH 1/2] docs(installation): call out isolation: isolate for portaled popups Floating components portal to document.body without a z-index, so a consumer's positive z-index (e.g. a sticky header) can paint over an open popup. Document the Base UI recommendation to add isolation: isolate to the app root, and note that fiddling with z-index is a sign something is off. Follow-up to #759. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01MJEuBSdUCbEytL2gbb6qio --- .../src/pages/installation.mdx | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/packages/kumo-docs-astro/src/pages/installation.mdx b/packages/kumo-docs-astro/src/pages/installation.mdx index 12473f2061..6fb7a0ab27 100644 --- a/packages/kumo-docs-astro/src/pages/installation.mdx +++ b/packages/kumo-docs-astro/src/pages/installation.mdx @@ -142,6 +142,42 @@ import "@cloudflare/kumo/styles/standalone"; The standalone build includes all Tailwind utilities and Kumo component styles pre-compiled. No Tailwind configuration needed! +## Isolate Your App Root + +Kumo's floating components (`Select`, `Combobox`, `Dropdown`, `Popover`, `Tooltip`, `Dialog`, and others) render their popups in a portal at the end of `document.body`. Because Kumo doesn't apply a `z-index` to these popups, any positive `z-index` in your own layout (a sticky header, for example) can paint above an open popup. + +To prevent this, add `isolation: isolate` to your application's root element, as [Base UI recommends](https://base-ui.com/react/overview/quick-start#portals): + +```css +/* The element that wraps your entire app, e.g. #root or #app */ +.root { + isolation: isolate; +} +``` + +Or with Tailwind: + +```tsx +
+ {/* Your app */} +
+``` + +This creates a separate stacking context for your app's content, so portaled popups always appear on top regardless of the `z-index` values used inside your layout. + + + If you find yourself reaching for `z-index` to get a Kumo popup to show above + your own UI, that's a sign something is off. The fix is almost always + isolating your app root as shown above, not raising the popup's `z-index` or + targeting Base UI's internal data attributes. + + + + **Important:** Apply `isolation: isolate` to the element that wraps your app's + content — not to `` or the portal container itself. Isolating the body + would put the portals inside the same stacking context and defeat the purpose. + + ## Usage Example Here's a complete example of using Kumo components with Tailwind CSS: From a909c8242b9aa6b890130d13fa70fada2887ac37 Mon Sep 17 00:00:00 2001 From: Matt Rothenberg Date: Sat, 12 Sep 2026 14:03:17 -0400 Subject: [PATCH 2/2] docs(installation): fold body warning into prose, keep single callout Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01MJEuBSdUCbEytL2gbb6qio --- packages/kumo-docs-astro/src/pages/installation.mdx | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/packages/kumo-docs-astro/src/pages/installation.mdx b/packages/kumo-docs-astro/src/pages/installation.mdx index 6fb7a0ab27..0b2a640efa 100644 --- a/packages/kumo-docs-astro/src/pages/installation.mdx +++ b/packages/kumo-docs-astro/src/pages/installation.mdx @@ -163,7 +163,7 @@ Or with Tailwind: ``` -This creates a separate stacking context for your app's content, so portaled popups always appear on top regardless of the `z-index` values used inside your layout. +This creates a separate stacking context for your app's content, so portaled popups always appear on top regardless of the `z-index` values used inside your layout. Apply it to the element that wraps your app's content, not to `` — isolating the body would put the portals inside the same stacking context and defeat the purpose. If you find yourself reaching for `z-index` to get a Kumo popup to show above @@ -172,12 +172,6 @@ This creates a separate stacking context for your app's content, so portaled pop targeting Base UI's internal data attributes. - - **Important:** Apply `isolation: isolate` to the element that wraps your app's - content — not to `` or the portal container itself. Isolating the body - would put the portals inside the same stacking context and defeat the purpose. - - ## Usage Example Here's a complete example of using Kumo components with Tailwind CSS: