How to properly deal with portal containers and the fullscreen API?

[snowystinger]

Discussed in #9206

^{Originally posted by janvorwerk November 19, 2025}
Hello gents,

My app is using the DOM fullscreen API for several cases.

Let's consider two of them:

1. Part of the screen needs a lot of screen space… and still has many interactions that will open portaled content (popover…)
2. A dialog (Modal for instance) is showing a Youtube iframe, in which the user wants to trigger full screen mode to better view the video

By default, case 1 does not work because as soon as the component goes fullscreen, the document.body seems no longer visible so that any portaled component isn't either.

What I thought was a very smart move was to use the PortalProvider… despite the fact that it was flagged "UNSAFE".

export function SkPortalProvider(props: { children: ReactNode }) {
  return <UNSAFE_PortalProvider getContainer={getDomRoot}>{props.children}</UNSAFE_PortalProvider>;
}

function getDomRoot(): HTMLElement | null {
  return document?.fullscreenElement instanceof HTMLElement ? document.fullscreenElement : document.body;
}

Clever, ugh? Actually not so much because then, case 2 won't work any longer : as soon as the video goes fullscreen, the portal is changed, so that the dialog containing the video node vanishes…

Then I tried to be more clever than ever 😁…

function getDomRoot(): HTMLElement | null {
    // If there are existing modals/dialogs in document.body, keep using document.body
    // to avoid moving them when fullscreen is triggered. This prevents modals from
    // disappearing when fullscreen is activated.
    const hasExistingModals = document.body?.querySelector('[role="dialog"], [role="alertdialog"]') != null;
    
    if (hasExistingModals) {
      return document.body;
    }
    
    // Otherwise, use fullscreen element if available (for popovers within fullscreen),
    // or document.body as fallback
    return document?.fullscreenElement instanceof HTMLElement ? document.fullscreenElement : document.body;
}

… but then case 1 no longer works properly…

Hence my questions: did you guys consider using/supporting fullscreen? How did you do?

Many thanks in advance 🙏

[janvorwerk]

Portals & the Fullscreen API — prior art analysis

Context

@snowystinger asked in discussion #9206:

"It would be interesting to see if an AI can find any prior art around this issue. Maybe that would be a good starting point for figuring out how we'd like to solve it."

This answer is my tokens contribution to the issue 😇, and Claude Opus 5 ultracode analysis.

Its purpose is to answer only that request: survey the prior art (web platform + other libraries + what already exists in this repo), extract the invariants, and propose a technical direction. Nothing is posted to GitHub.

The two cases from the issue:

• Case 1 — part of the app enters fullscreen; popovers/menus/dialogs portalled into document.body are painted underneath the fullscreen element's ::backdrop → invisible.
• Case 2 — a react-aria Modal contains a YouTube <iframe>; the user triggers fullscreen from the video. document.fullscreenElement becomes the iframe, getContainer() returns the iframe, React re-targets the portal → the modal vanishes.

No getContainer(): HTMLElement taking no argument can satisfy both cases. That is the crux of the problem.

---

1. Exact mechanics (why it breaks)

1.1 The top layer

An element entering fullscreen is promoted into the top layer — an ordered set shared with dialog.showModal() and element.showPopover() (MDN — Top layer). An opaque ::backdrop is painted immediately below it. Anything that is neither the fullscreen element nor one of its descendants stays in the DOM, stays focusable, but is painted under the backdrop → invisible and unclickable. z-index has no effect.

1.2 React remounts the subtree when the portal target changes

ReactDOM.createPortal(children, container): the reconciler compares containerInfo by identity. If it changes, the portal fiber is deleted and recreated → full unmount/remount of the subtree: state lost, focus lost, animations cut, and crucially any contained <iframe> reloads. That is exactly what destroys case 2. See facebook/react#12247.

The repo already concedes this implicitly: the withFullscreen story forces a remount with different keys — Toast.stories.tsx:366-398:

{isFullscreen && <ToastContainer key="miniapp" ... />}
...
{!isFullscreen && <ToastContainer key="app" ... />}

---

2. Current state of the code in this repo

2.1 The critical path

Overlay.tsx:53-66:

let {portalContainer = isSSR ? null : document.body, isExiting} = props;
let {getContainer} = useUNSAFE_PortalContext();
if (!props.portalContainer && getContainer) {
  portalContainer = getContainer();      // ← called during RENDER, never memoized
}
...
return ReactDOM.createPortal(contents, portalContainer);

Three consequences:

1. getContainer() is an impure DOM read during render (problematic under concurrent rendering / StrictMode).
2. It is re-evaluated on every render of the Overlay — so any change in the returned value remounts the portal.
3. PortalProvider.tsx:32-36 recreates the {getContainer: …} context object on every render → all consumers re-render whenever the provider does. In Jan's repro the app re-renders on fullscreenchange (to update the button label), which closes the loop.

2.2 The other consumers of the context

File	Line	Usage
Overlay.tsx	59-62	Popover, Modal, Tooltip (RAC + RSP)
useModal.tsx	131-133	OverlayContainer (legacy API)
Toaster.tsx	70	getContainer?.() ?? document.body
Toast.tsx	79-85	RAC ToastRegion
Resizer.tsx	136	Table column resizer

2.3 History

• #6141 (snowystinger, 2024-04-27) — introduces UNSAFE_PortalProvider, "an alternative to Expose UNSTABLE container for RSP overlays #5944 using context… allows users to generate the container on demand". Partly motivated by fullscreen (confirmed by Rob in the discussion), with no fullscreen tests.
• #7907 (armandabric) + #7976 (LFDanLu) — portalContainer on ToastRegion, deprecation of UNSTABLE_portalContainer.
• #8185, #8135 — typings + export from the react-aria monopackage.

The docs already warn (PortalProvider.mdx:37-43): "there are many places that an application could portal to. Not all of them will work".

2.4 What react-aria already gets right, and what it doesn't

Topic	Status	Reference
Escape must not exit fullscreen when closing an overlay	✅ already correct — e.preventDefault()	useOverlay.ts:112-119
In-house "top layer" concept (toasts not aria-hidden, focus allowed, no outside-dismiss)	✅ exists: data-react-aria-top-layer	useToastRegion.ts:184, ariaHideOutside.ts:63,149, FocusScope.tsx:447, useInteractOutside.ts:127
ariaHideOutside with root = document.body	✅ still correct even when the overlay is portalled into the fullscreen element	ariaHideOutside.ts:43
Scroll locking	⚠️ broken in fullscreen — overflow:hidden applied to document.documentElement only; the fullscreen container keeps its own scroll	usePreventScroll.ts:72-81
Positioning — boundaryElement defaults to document.body	⚠️ in fullscreen the containing block becomes the fullscreen element (position:fixed; inset:0 via the UA stylesheet); bounds computed against body can diverge	useOverlayPosition.ts:103, calculatePosition.ts:570-600
Reusable shadow-DOM-safe helpers	✅ nodeContains, getOwnerDocument	DOMFunctions.ts:9, domHelpers.ts

---

3. Prior art, ranked by relevance

⭐⭐⭐ A. Ariakit — the only React library that has actually implemented case 1

• Issue ariakit#865 "Tooltip doesn't show up in fullscreen mode", opened April 2021, resolved April 2026 by PR #5742 (shipped in @ariakit/react@0.4.26).
• Worth noting: back in 2021 Diego Haz already wrote "Can we detect that specific DOM node on full screen so we can attach the portal to it instead? … It looks like we could use fullscreenchange". It took 5 years.

The mechanism (current source, packages/ariakit-react-components/src/portal/portal.tsx):

function getRootElement(element?: Element | null) {
  const doc = getDocument(element);
  const {fullscreenElement} = doc;
  const HTMLElementClass = getWindow(element).HTMLElement;
  if (HTMLElementClass && fullscreenElement instanceof HTMLElementClass) {
    return fullscreenElement;
  }
  return doc.body;
}

// Move the portal node when fullscreen state changes so it stays visible.
useEffect(() => {
  if (!portalNode) return;
  if (context) return;         // ← disabled when the app supplies a PortalContext
  if (portalElement) return;   // ← or an explicit container
  const doc = getDocument(portalNode);
  const onFullscreenChange = () => {
    const rootElement = getRootElement(portalNode);
    if (portalNode.parentElement !== rootElement) {
      rootElement.appendChild(portalNode);   // ← imperative DOM move
    }
  };
  if (portalNode.isConnected) onFullscreenChange();   // guard added by #6586
  doc.addEventListener("fullscreenchange", onFullscreenChange);
  return () => doc.removeEventListener("fullscreenchange", onFullscreenChange);
}, [portalNode, context, portalElement]);

Three ideas to take away:

1. Ariakit never changes the React portal target. Each Portal owns a stable host node (<div id="portal/xxx">) that React portals into; it is that node that gets appendChilded elsewhere. React sees nothing → no remount, the iframe does not reload. This is the structural difference from react-aria's getContainer() approach.
2. The automatic sync is disabled as soon as the app supplies its own container (context / portalElement). Exactly the same contract as UNSAFE_PortalProvider: the escape hatch always wins.
3. The StrictMode trap: ariakit#6585 (July 2026) — the immediate sync resurrected already-removed nodes (parentElement === null !== body → appendChild), leaving orphaned containers in Gutenberg/WordPress. Fixed in #6586 with a one-liner if (!portalNode.isConnected) return.

Unsolved limitation in Ariakit — precisely Jan's case 2. getRootElement() only looks at document.fullscreenElement, with no contains guard. If the fullscreen element is a descendant of the portal node (the video inside the modal), then rootElement.appendChild(portalNode) tries to insert a node into its own descendant → DOMException: HierarchyRequestError. So Ariakit carries the same latent bug as the Angular CDK (see B).

Ariakit also shipped 3 Playwright tests (site/src/sandbox/tooltip-865/test-browser.ts) that form a directly transposable test baseline:

• the tooltip opens inside the fullscreen element;
• it moves back to body after exiting fullscreen;
• a tooltip mounted while in fullscreen also renders inside it.

⭐⭐⭐ B. Angular CDK — FullscreenOverlayContainer (since 2016)

The same idea, 10 years earlier, with a single global container (.cdk-overlay-container):

@Service()
export class FullscreenOverlayContainer extends OverlayContainer implements OnDestroy {
  protected override _createContainer(): void {
    const eventName = this._getEventName();     // fullscreenchange | webkit | moz | MS
    super._createContainer();
    this._adjustParentForFullscreenChange();
    if (eventName) {
      this._cleanupFullScreenListener = this._renderer.listen('document', eventName,
        () => this._adjustParentForFullscreenChange());
    }
  }
  private _adjustParentForFullscreenChange(): void {
    if (this._containerElement) {
      const parent = this.getFullscreenElement() || this._document.body;
      parent.appendChild(this._containerElement);   // ← DOM move, not recreation
    }
  }
}

Explicit opt-in: {provide: OverlayContainer, useClass: FullscreenOverlayContainer}.

And above all: angular/components#10679 — "Full-screen overlay container doesn't work when fullscreen element is within an overlay", OPEN since April 2018. This is Jan's case 2, verbatim:

ERROR DOMException: Failed to execute 'appendChild' on 'Node': The new child element contains the parent.
at FullscreenOverlayContainer._adjustParentForFullscreenChange

Jeremy Elbourn (Angular Material maintainer):

"Looks like this doesn't work when trying to make the fullscreen element be within an overlay itself. I don't really see a good way to fix this, since the overlay container needs to be inside the fullscreen element for subsequent overlays to work."

Still unresolved 8 years later, with a steady trickle of "me too" reports (fullscreen map inside a modal, invisible dropdown…). See also #25840 (menu invisible with mat-dialog + FullscreenOverlayContainer) and a report that it does not work on Android.

The single most important conclusion of this whole review: case 1 is a solved problem elsewhere; case 2 is solved nowhere. Jan couldn't find a clean workaround because none exists in the state of the art.

⭐⭐ C. Ant Design — getPopupContainer(triggerNode): the right API shape

Ant Design has always solved this, but with a different signature: the container is computed from the trigger node, not from global state.

<ConfigProvider getPopupContainer={node => node ? node.parentNode : document.body}>

The recommended triggerNode => triggerNode.parentNode pattern makes the popup appear where its trigger lives — hence automatically inside the fullscreen subtree if the trigger is there, and outside otherwise. No need to know anything about document.fullscreenElement.

Documented limitations on the Ant Design side, worth not reproducing: triggerNode is undefined for static APIs (Modal.confirm, message) — hence the node ? … : document.body — and an overflow: hidden ancestor re-clips the popup (#18797, FAQ).

This is exactly where react-aria's API falls short: getContainer?: () => HTMLElement | null receives no context at all. Writing a correct rule is impossible. That is why Jan had to fall back on document.body.querySelector('[role="dialog"]') and then on the data-fullscreen="true" hack.

⭐ D. Radix UI / shadcn — no built-in solution, the problem is still open

• radix#885 (Oct 2021) "[DropdownMenu] Portal not displaying when parent element is fullscreen". jjenzz's diagnosis: "It's because the element you are making full screen isn't the body and we portal everything into the body". Workaround at the time: portalled={false} (breaks positioning). Closed by #1303, which adds a container prop on *.Portal — i.e. the equivalent of UNSAFE_PortalProvider: the escape hatch, not the solution.
• The problem simply moved one level down: on the shadcn/ui side it is still open — #7040 "Popover not showing in window.document.fullscreen element", #7178 "Fullscreen: Dialog, Popover not showing", #8806 (Nov 2025) "DropdownMenu & Select not usable inside browser Fullscreen mode".
• The community workaround on test: adds ShadowDOM / UNSAFE_PortalProvider tests #8806 is literally Jan's first attempt: useState + a fullscreenchange listener + container={document.fullscreenElement}. Nobody in that thread mentions case 2.

Radix bonus, relevant to react-aria: radix#1420 / #1751 — "Escape key exits fullscreen on Firefox & Safari" (Escape closes the menu and leaves fullscreen; Chrome uses a different shortcut). The reporter writes: "it works correctly in other libraries, e.g. React Spectrum". react-aria is already the reference on this point, thanks to the e.preventDefault() in useOverlay.ts:116 — an asset not to lose in a refactor.

⭐ E. The rest — same diagnosis, prop-based workaround, no automatic sync

Library	Container API	Fullscreen trace
Headless UI	<Portal> / <PortalGroup target> + #headlessui-portal-root root	discussion #1542 — neat trick: put id="headlessui-portal-root" on the div you take fullscreen. Resolution by selector, not by reference. No maintainer reply.
Floating UI	<FloatingPortal root>	#1421 "Tooltip position gets shifted when switched into Fullscreen mode" (closed for lack of a repro) — corroborates the positioning point in §2.4
Chakra UI	<Portal containerRef>	#6373 "Tooltip does not work with Fullscreen API"
Mantine	<Portal target>	#3795 "Components not visible when using use-fullscreen hook"
MUI / Base UI	container on Portal/Modal/Popper	nothing fullscreen-specific
PrimeReact	appendTo="self" | element	appendTo="self" is the "render in place" variant

None of them syncs automatically. Ariakit stands alone.

⭐⭐ F. Web platform — the native top layer

This is the only route that solves case 1 without moving anything, since the top layer is independent of DOM position.

What works:

• A <dialog>.showModal() or element.showPopover() triggered after entering fullscreen is promoted above the fullscreen element (the top layer is an ordered set, by promotion order).

What doesn't:

• requestFullscreen() runs "hide all popovers": a native popover opened before is force-closed (Fullscreen Standard, MDN popover). A library therefore cannot rely on it to "survive" entering fullscreen.
• No ordering control → whatwg/html#11193 "Persistent element at the top of the top layer" (use case: a toast that must stay above a dialog; "there is no reliable way to know when something is added to the top-layer"). That is exactly the need behind data-react-aria-top-layer.
• Inertness: a popover that is not a descendant of the topmost modal dialog is rendered above it but not interactive → whatwg/html#9936, #11195.
• Undetectable: no reliable way in JS or CSS to know an element is in the top layer, notably during exit animations → fortanix/baklava#88, a remarkable synthesis of all these limits.

→ A credible long-term direction, but not an answer to #10506 today.

⭐⭐ G. Video players — the strategy that actually works in production

media-chrome (Mux), Video.js, Vidstack: they don't portal at all. Menus (quality, captions, speed) are rendered inside the player container, which is also the subject of requestFullscreen(). The portal container is therefore, by construction, a guaranteed descendant of the fullscreen subject.

This is the strongest argument for resolving relative to the trigger rather than to global state: these libraries never had this bug because their "container" is structural.

---

4. Invariants extracted from the prior art

1. Move the DOM node; do not re-target the React portal. (Ariakit, Angular CDK) Otherwise: remount, iframe reload, focus loss.
2. Choose the container relative to the trigger, not to global state. (Ant Design, video players) A getContainer() with no argument cannot be correct.
3. A bidirectional contains() guard is mandatory. Without it → HierarchyRequestError (open bug for 8 years at Angular, latent at Ariakit).
4. An isConnected guard on any imperative sync. (ariakit#6585 / StrictMode)
5. Listen for fullscreenchange + prefixes (webkitfullscreenchange, mozfullscreenchange, MSFullscreenChange — the CDK still does).
6. Don't regress on Escape (preventDefault, already in place here).
7. Scroll locking and positioning must follow the container, not document.documentElement / document.body.
8. The app's explicit escape hatch must always beat any automatic heuristic.

---

5. Proposed direction for react-aria

5.1 The correct resolution rule: "the trigger's nearest fullscreen ancestor"

document.fullscreenElement returns the top of the fullscreen stack — the wrong piece of information. What's needed is the trigger's nearest ancestor whose fullscreen flag is set, which :fullscreen exposes (it matches every element in the stack):

function getFullscreenRoot(trigger: Element | null): HTMLElement | null {
  if (!trigger || !supportsFullscreenSelector) return null;
  return trigger.closest(':fullscreen') as HTMLElement | null;   // + :-webkit-full-screen fallback
}

// container = getFullscreenRoot(triggerNode) ?? getOwnerDocument(triggerNode).body

Checked against the two cases in the issue:

Scenario	Fullscreen stack	Trigger	closest(':fullscreen')	Result
Case 1 — <main> fullscreen, open a popover	[main]	button inside main	main	✅ portalled into main, visible
Case 2 — nothing fullscreen, the video of an open modal goes fullscreen	[iframe]	button outside the iframe	null	✅ container unchanged → the modal doesn't move, the video plays above
Case 1+2 (Jan's repro) — main fullscreen, modal inside it, video goes fullscreen	[main, iframe]	button inside main	main	✅ the modal stays in main, untouched
Exiting fullscreen	[]	—	null	✅ back to body

This is the Ant Design synthesis (trigger-relative) + Ariakit (DOM move) that nobody has written yet. Implementation notes: wrap closest in a support test (an invalid selector throws), and remember closest does not cross shadow roots — the repo already has nodeContains for that.

5.2 Two workstreams, separable

(a) Fix the remount — necessary regardless of what follows.
Introduce a stable host node per overlay (Ariakit-style) in Overlay.tsx: React always portals into that node; that node is what gets appendChilded elsewhere on fullscreenchange, with isConnected + bidirectional contains guards. Immediate benefit even outside fullscreen: getContainer() stops being called during render.

(b) Widen the getContainer signature — backwards compatible, since existing callbacks simply ignore the argument:

getContainer?: ((options?: {trigger?: Element | null}) => HTMLElement | null) | null

This would let Jan write, with no hack at all:

getContainer={({trigger}) => trigger?.closest(':fullscreen') ?? document.body}

And it would let react-aria eventually make that the default behavior — like Ariakit — while preserving invariant 8: as soon as a PortalProvider or an explicit portalContainer is supplied, the automatic sync switches off.

(c) Side effects to address alongside — see §2.4: usePreventScroll must lock the fullscreen container rather than documentElement; useOverlayPosition should default boundaryElement to the fullscreen element when one exists.

5.3 Verification

• Reference repro: janvorwerk/react-aria-fullscreen (Vercel demo linked from the repo), already written by Jan and cited by Rob as a test basis.
• Storybook: extend Toast.stories.tsx › withFullscreen to Popover/Modal/Menu, and remove the keys that currently mask the remount.
• Browser tests: transpose Ariakit's 3 Playwright tests (site/src/sandbox/tooltip-865/test-browser.ts), plus two that nobody has ever written — (1) fullscreen triggered from inside an open overlay: the overlay does not move and no HierarchyRequestError is thrown; (2) the overlay's <iframe> is not reloaded (load counter).
• Fullscreen cannot be simulated in jsdom: these tests must live in a browser runner, not in Jest.

---

One-sentence summary

Case 1 has a proven solution — move a stable host node into the fullscreen element on fullscreenchange (Angular CDK since 2016, Ariakit since April 2026); case 2 is solved nowhere, and both reference implementations throw the same HierarchyRequestError on it — because both query document.fullscreenElement (global state) instead of resolving the container relative to the trigger, the way Ant Design does and the way every video player does structurally.