Skip to content

docs(installation): call out isolation: isolate for portaled popups #800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattrothenberg merged 2 commits into from
Sep 14, 2026
+30 −0
Merged

docs(installation): call out isolation: isolate for portaled popups #800

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
51b8f0b
docs(installation): call out isolation: isolate for portaled popups
mattrothenberg Sep 12, 2026
a909c82
docs(installation): fold body warning into prose, keep single callout
mattrothenberg Sep 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions packages/kumo-docs-astro/src/pages/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,36 @@ 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
<div id="root" className="isolate">
{/* Your app */}
</div>
```

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 `<body>` — isolating the body would put the portals inside the same stacking context and defeat the purpose.

<Callout type="info">
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.
</Callout>

## Usage Example

Here's a complete example of using Kumo components with Tailwind CSS:
Expand Down
Loading