Skip to content

docs: guide portal stacking isolation #803

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 3 commits into from
Sep 14, 2026
Merged

docs: guide portal stacking isolation #803

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e02acaa
docs: guide portal stacking isolation
mattrothenberg Sep 14, 2026
bcea7b2
Merge branch 'main' into docs/guide-portal-stacking-isolation
mattrothenberg Sep 14, 2026
bf3a23c
Update AGENTS.md
mattrothenberg Sep 14, 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
5 changes: 5 additions & 0 deletions .changeset/portal-stacking-guidance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@cloudflare/kumo": patch
---

Document app-root CSS isolation for reliable stacking of portaled components.
9 changes: 9 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,15 @@ kumo/
- **Surface hierarchy**: `bg-kumo-base` → `bg-kumo-elevated` → `bg-kumo-recessed`
- **Mode/theme**: `data-mode="light"|"dark"` + `data-theme="fedramp"` on parent element

### Portal stacking (CRITICAL)

- Kumo floating components portal to `document.body`. Consumers should create an
app-root stacking context with `isolation: isolate` (Tailwind:
`className="isolate"`).
- Do **not** fix a popup that appears below consumer content by adding `z-index`
to Kumo popup components, targeting Base UI internal data attributes, or
applying `isolation` to `<body>`.

### Components

- **Scaffold new**: `pnpm --filter @cloudflare/kumo new:component` (never create manually)
Expand Down
4 changes: 4 additions & 0 deletions packages/kumo/src/utils/portal-provider.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ const PortalContainerContext = createContext<PortalContainer>(null);
* When not provided, overlays portal to `document.body` (default browser behavior).
* Individual components can override this via their own `container` prop.
*
* For app-wide portal stacking, consumers should set `isolation: isolate` on
* their app root (not `<body>`). Do not add z-index workarounds to Kumo's
* portaled components or target Base UI internal data attributes.
*
* @example Shadow DOM usage
* ```tsx
* function WebComponent() {
Expand Down
Loading