feat(headless): hold Popover contents while it closes

.changeset/popover-freeze-on-close.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/popover/README.md

@@ -105,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,72 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds state updates raised from inside the frozen subtree', () => {
+ function Counter({ count }: { count: number }) {
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter count={0} />
+ </Freeze>,
+ );
+
+ rerender(
+ <Freeze frozen>
+ <Counter count={1} />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+ });
+});

packages/headless/src/utils/freeze.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Never settles. Throwing it suspends the enclosing boundary indefinitely: React keeps
+ * rendering the subtree but holds the commit, so the DOM keeps painting its last frame.
+ */
+const never = new Promise<never>(() => {});
+
+function Suspend(): null {
+ // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspending is React's thrown-thenable protocol, not an error. `React.use()` would say this more plainly but needs React 19.2; this package supports React 18.
+ throw never;
+}
+
+export interface FreezeProps {
+ /** While `true`, the DOM below holds whatever it last committed. */
+ frozen: boolean;
+ children?: React.ReactNode;
+}
+
+/**
+ * Holds its subtree's DOM at the last committed frame while `frozen`. Renders keep
+ * happening, they just don't reach the DOM; the pending one commits when `frozen` flips
+ * back to `false`.
+ *
+ * Use it to stop content from visibly changing under an exit animation — a popover that
+ * closes because the thing it was showing changed would otherwise swap its contents on the
+ * way out.
+ */
+export function Freeze({ frozen, children }: FreezeProps) {
+ const contentRef = React.useRef<HTMLDivElement | null>(null);
+
+ // Hold onto the node ourselves rather than reading a plain ref: hiding a boundary's children
+ // detaches their refs, so by the time the effect below runs a normal ref reads `null`.
+ const setContent = React.useCallback((node: HTMLDivElement | null) => {
+ if (node) {
+ contentRef.current = node;
+ }
+ }, []);
+
+ // React hides a suspended boundary's host children with `display: none !important`, which is
+ // the opposite of what this is for. Undo it on the commit that applies it: insertion effects
+ // run after the boundary's mutation and before paint, so the held frame never blinks out.
+ // `display: contents` is also what the wrapper renders with, so React puts it back on unfreeze
+ // and the wrapper stays out of the layout it is spliced into.
+ React.useInsertionEffect(() => {
+ if (frozen) {
+ contentRef.current?.style.setProperty('display', 'contents');
+ }
+ }, [frozen]);
+
+ return (
+ <React.Suspense fallback={null}>
+ {frozen ? <Suspend /> : null}
+ <div
+ ref={setContent}
+ style={{ display: 'contents' }}
+ >
+ {children}
+ </div>
+ </React.Suspense>
+ );
+}

packages/headless/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { cssVars } from './css-vars';
+export { Freeze, type FreezeProps } from './freeze';
 export { resetLayoutStyles } from './reset-layout-styles';
 export {
  type ComponentProps,

packages/ui/src/mosaic/components/popover/popover.test.tsx

@@ -113,7 +113,7 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- const popup = screen.getByText('Body');
+ const popup = document.querySelector('.cl-popover-popup');
  expect(popup).toHaveClass('cl-popover-popup', 'my-popup');
  expect(popup).toHaveStyle({ marginTop: '8px' });
  });
@@ -235,6 +235,6 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- expect(ref.current).toBe(screen.getByText('Body'));
+ expect(ref.current).toBe(document.querySelector('.cl-popover-popup'));
  });
 });

.changeset/popover-freeze-on-close.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/popover/README.md

@@ -105,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,72 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds state updates raised from inside the frozen subtree', () => {
+ function Counter({ count }: { count: number }) {
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter count={0} />
+ </Freeze>,
+ );
+
+ rerender(
+ <Freeze frozen>
+ <Counter count={1} />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+ });
+});

packages/headless/src/utils/freeze.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Never settles. Throwing it suspends the enclosing boundary indefinitely: React keeps
+ * rendering the subtree but holds the commit, so the DOM keeps painting its last frame.
+ */
+const never = new Promise<never>(() => {});
+
+function Suspend(): null {
+ // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspending is React's thrown-thenable protocol, not an error. `React.use()` would say this more plainly but needs React 19.2; this package supports React 18.
+ throw never;
+}
+
+export interface FreezeProps {
+ /** While `true`, the DOM below holds whatever it last committed. */
+ frozen: boolean;
+ children?: React.ReactNode;
+}
+
+/**
+ * Holds its subtree's DOM at the last committed frame while `frozen`. Renders keep
+ * happening, they just don't reach the DOM; the pending one commits when `frozen` flips
+ * back to `false`.
+ *
+ * Use it to stop content from visibly changing under an exit animation — a popover that
+ * closes because the thing it was showing changed would otherwise swap its contents on the
+ * way out.
+ */
+export function Freeze({ frozen, children }: FreezeProps) {
+ const contentRef = React.useRef<HTMLDivElement | null>(null);
+
+ // Hold onto the node ourselves rather than reading a plain ref: hiding a boundary's children
+ // detaches their refs, so by the time the effect below runs a normal ref reads `null`.
+ const setContent = React.useCallback((node: HTMLDivElement | null) => {
+ if (node) {
+ contentRef.current = node;
+ }
+ }, []);
+
+ // React hides a suspended boundary's host children with `display: none !important`, which is
+ // the opposite of what this is for. Undo it on the commit that applies it: insertion effects
+ // run after the boundary's mutation and before paint, so the held frame never blinks out.
+ // `display: contents` is also what the wrapper renders with, so React puts it back on unfreeze
+ // and the wrapper stays out of the layout it is spliced into.
+ React.useInsertionEffect(() => {
+ if (frozen) {
+ contentRef.current?.style.setProperty('display', 'contents');
+ }
+ }, [frozen]);
+
+ return (
+ <React.Suspense fallback={null}>
+ {frozen ? <Suspend /> : null}
+ <div
+ ref={setContent}
+ style={{ display: 'contents' }}
+ >
+ {children}
+ </div>
+ </React.Suspense>
+ );
+}

packages/headless/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { cssVars } from './css-vars';
+export { Freeze, type FreezeProps } from './freeze';
 export { resetLayoutStyles } from './reset-layout-styles';
 export {
  type ComponentProps,

packages/ui/src/mosaic/components/popover/popover.test.tsx

@@ -113,7 +113,7 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- const popup = screen.getByText('Body');
+ const popup = document.querySelector('.cl-popover-popup');
  expect(popup).toHaveClass('cl-popover-popup', 'my-popup');
  expect(popup).toHaveStyle({ marginTop: '8px' });
  });
@@ -235,6 +235,6 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- expect(ref.current).toBe(screen.getByText('Body'));
+ expect(ref.current).toBe(document.querySelector('.cl-popover-popup'));
  });
 });

.changeset/popover-freeze-on-close.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/popover/README.md

@@ -105,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,72 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds state updates raised from inside the frozen subtree', () => {
+ function Counter({ count }: { count: number }) {
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter count={0} />
+ </Freeze>,
+ );
+
+ rerender(
+ <Freeze frozen>
+ <Counter count={1} />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+ });
+});

packages/headless/src/utils/freeze.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Never settles. Throwing it suspends the enclosing boundary indefinitely: React keeps
+ * rendering the subtree but holds the commit, so the DOM keeps painting its last frame.
+ */
+const never = new Promise<never>(() => {});
+
+function Suspend(): null {
+ // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspending is React's thrown-thenable protocol, not an error. `React.use()` would say this more plainly but needs React 19.2; this package supports React 18.
+ throw never;
+}
+
+export interface FreezeProps {
+ /** While `true`, the DOM below holds whatever it last committed. */
+ frozen: boolean;
+ children?: React.ReactNode;
+}
+
+/**
+ * Holds its subtree's DOM at the last committed frame while `frozen`. Renders keep
+ * happening, they just don't reach the DOM; the pending one commits when `frozen` flips
+ * back to `false`.
+ *
+ * Use it to stop content from visibly changing under an exit animation — a popover that
+ * closes because the thing it was showing changed would otherwise swap its contents on the
+ * way out.
+ */
+export function Freeze({ frozen, children }: FreezeProps) {
+ const contentRef = React.useRef<HTMLDivElement | null>(null);
+
+ // Hold onto the node ourselves rather than reading a plain ref: hiding a boundary's children
+ // detaches their refs, so by the time the effect below runs a normal ref reads `null`.
+ const setContent = React.useCallback((node: HTMLDivElement | null) => {
+ if (node) {
+ contentRef.current = node;
+ }
+ }, []);
+
+ // React hides a suspended boundary's host children with `display: none !important`, which is
+ // the opposite of what this is for. Undo it on the commit that applies it: insertion effects
+ // run after the boundary's mutation and before paint, so the held frame never blinks out.
+ // `display: contents` is also what the wrapper renders with, so React puts it back on unfreeze
+ // and the wrapper stays out of the layout it is spliced into.
+ React.useInsertionEffect(() => {
+ if (frozen) {
+ contentRef.current?.style.setProperty('display', 'contents');
+ }
+ }, [frozen]);
+
+ return (
+ <React.Suspense fallback={null}>
+ {frozen ? <Suspend /> : null}
+ <div
+ ref={setContent}
+ style={{ display: 'contents' }}
+ >
+ {children}
+ </div>
+ </React.Suspense>
+ );
+}

packages/headless/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { cssVars } from './css-vars';
+export { Freeze, type FreezeProps } from './freeze';
 export { resetLayoutStyles } from './reset-layout-styles';
 export {
  type ComponentProps,

packages/ui/src/mosaic/components/popover/popover.test.tsx

@@ -113,7 +113,7 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- const popup = screen.getByText('Body');
+ const popup = document.querySelector('.cl-popover-popup');
  expect(popup).toHaveClass('cl-popover-popup', 'my-popup');
  expect(popup).toHaveStyle({ marginTop: '8px' });
  });
@@ -235,6 +235,6 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- expect(ref.current).toBe(screen.getByText('Body'));
+ expect(ref.current).toBe(document.querySelector('.cl-popover-popup'));
  });
 });

.changeset/popover-freeze-on-close.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/popover/README.md

@@ -105,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,72 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds state updates raised from inside the frozen subtree', () => {
+ function Counter({ count }: { count: number }) {
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter count={0} />
+ </Freeze>,
+ );
+
+ rerender(
+ <Freeze frozen>
+ <Counter count={1} />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+ });
+});

packages/headless/src/utils/freeze.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Never settles. Throwing it suspends the enclosing boundary indefinitely: React keeps
+ * rendering the subtree but holds the commit, so the DOM keeps painting its last frame.
+ */
+const never = new Promise<never>(() => {});
+
+function Suspend(): null {
+ // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspending is React's thrown-thenable protocol, not an error. `React.use()` would say this more plainly but needs React 19.2; this package supports React 18.
+ throw never;
+}
+
+export interface FreezeProps {
+ /** While `true`, the DOM below holds whatever it last committed. */
+ frozen: boolean;
+ children?: React.ReactNode;
+}
+
+/**
+ * Holds its subtree's DOM at the last committed frame while `frozen`. Renders keep
+ * happening, they just don't reach the DOM; the pending one commits when `frozen` flips
+ * back to `false`.
+ *
+ * Use it to stop content from visibly changing under an exit animation — a popover that
+ * closes because the thing it was showing changed would otherwise swap its contents on the
+ * way out.
+ */
+export function Freeze({ frozen, children }: FreezeProps) {
+ const contentRef = React.useRef<HTMLDivElement | null>(null);
+
+ // Hold onto the node ourselves rather than reading a plain ref: hiding a boundary's children
+ // detaches their refs, so by the time the effect below runs a normal ref reads `null`.
+ const setContent = React.useCallback((node: HTMLDivElement | null) => {
+ if (node) {
+ contentRef.current = node;
+ }
+ }, []);
+
+ // React hides a suspended boundary's host children with `display: none !important`, which is
+ // the opposite of what this is for. Undo it on the commit that applies it: insertion effects
+ // run after the boundary's mutation and before paint, so the held frame never blinks out.
+ // `display: contents` is also what the wrapper renders with, so React puts it back on unfreeze
+ // and the wrapper stays out of the layout it is spliced into.
+ React.useInsertionEffect(() => {
+ if (frozen) {
+ contentRef.current?.style.setProperty('display', 'contents');
+ }
+ }, [frozen]);
+
+ return (
+ <React.Suspense fallback={null}>
+ {frozen ? <Suspend /> : null}
+ <div
+ ref={setContent}
+ style={{ display: 'contents' }}
+ >
+ {children}
+ </div>
+ </React.Suspense>
+ );
+}

packages/headless/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { cssVars } from './css-vars';
+export { Freeze, type FreezeProps } from './freeze';
 export { resetLayoutStyles } from './reset-layout-styles';
 export {
  type ComponentProps,

packages/ui/src/mosaic/components/popover/popover.test.tsx

@@ -113,7 +113,7 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- const popup = screen.getByText('Body');
+ const popup = document.querySelector('.cl-popover-popup');
  expect(popup).toHaveClass('cl-popover-popup', 'my-popup');
  expect(popup).toHaveStyle({ marginTop: '8px' });
  });
@@ -235,6 +235,6 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- expect(ref.current).toBe(screen.getByText('Body'));
+ expect(ref.current).toBe(document.querySelector('.cl-popover-popup'));
  });
 });

.changeset/popover-freeze-on-close.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/popover/README.md

@@ -105,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,72 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds state updates raised from inside the frozen subtree', () => {
+ function Counter({ count }: { count: number }) {
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter count={0} />
+ </Freeze>,
+ );
+
+ rerender(
+ <Freeze frozen>
+ <Counter count={1} />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+ });
+});

packages/headless/src/utils/freeze.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Never settles. Throwing it suspends the enclosing boundary indefinitely: React keeps
+ * rendering the subtree but holds the commit, so the DOM keeps painting its last frame.
+ */
+const never = new Promise<never>(() => {});
+
+function Suspend(): null {
+ // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspending is React's thrown-thenable protocol, not an error. `React.use()` would say this more plainly but needs React 19.2; this package supports React 18.
+ throw never;
+}
+
+export interface FreezeProps {
+ /** While `true`, the DOM below holds whatever it last committed. */
+ frozen: boolean;
+ children?: React.ReactNode;
+}
+
+/**
+ * Holds its subtree's DOM at the last committed frame while `frozen`. Renders keep
+ * happening, they just don't reach the DOM; the pending one commits when `frozen` flips
+ * back to `false`.
+ *
+ * Use it to stop content from visibly changing under an exit animation — a popover that
+ * closes because the thing it was showing changed would otherwise swap its contents on the
+ * way out.
+ */
+export function Freeze({ frozen, children }: FreezeProps) {
+ const contentRef = React.useRef<HTMLDivElement | null>(null);
+
+ // Hold onto the node ourselves rather than reading a plain ref: hiding a boundary's children
+ // detaches their refs, so by the time the effect below runs a normal ref reads `null`.
+ const setContent = React.useCallback((node: HTMLDivElement | null) => {
+ if (node) {
+ contentRef.current = node;
+ }
+ }, []);
+
+ // React hides a suspended boundary's host children with `display: none !important`, which is
+ // the opposite of what this is for. Undo it on the commit that applies it: insertion effects
+ // run after the boundary's mutation and before paint, so the held frame never blinks out.
+ // `display: contents` is also what the wrapper renders with, so React puts it back on unfreeze
+ // and the wrapper stays out of the layout it is spliced into.
+ React.useInsertionEffect(() => {
+ if (frozen) {
+ contentRef.current?.style.setProperty('display', 'contents');
+ }
+ }, [frozen]);
+
+ return (
+ <React.Suspense fallback={null}>
+ {frozen ? <Suspend /> : null}
+ <div
+ ref={setContent}
+ style={{ display: 'contents' }}
+ >
+ {children}
+ </div>
+ </React.Suspense>
+ );
+}

packages/headless/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { cssVars } from './css-vars';
+export { Freeze, type FreezeProps } from './freeze';
 export { resetLayoutStyles } from './reset-layout-styles';
 export {
  type ComponentProps,

packages/ui/src/mosaic/components/popover/popover.test.tsx

@@ -113,7 +113,7 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- const popup = screen.getByText('Body');
+ const popup = document.querySelector('.cl-popover-popup');
  expect(popup).toHaveClass('cl-popover-popup', 'my-popup');
  expect(popup).toHaveStyle({ marginTop: '8px' });
  });
@@ -235,6 +235,6 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- expect(ref.current).toBe(screen.getByText('Body'));
+ expect(ref.current).toBe(document.querySelector('.cl-popover-popup'));
  });
 });

.changeset/popover-freeze-on-close.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/popover/README.md

@@ -105,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,72 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds state updates raised from inside the frozen subtree', () => {
+ function Counter({ count }: { count: number }) {
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter count={0} />
+ </Freeze>,
+ );
+
+ rerender(
+ <Freeze frozen>
+ <Counter count={1} />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+ });
+});

packages/headless/src/utils/freeze.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Never settles. Throwing it suspends the enclosing boundary indefinitely: React keeps
+ * rendering the subtree but holds the commit, so the DOM keeps painting its last frame.
+ */
+const never = new Promise<never>(() => {});
+
+function Suspend(): null {
+ // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspending is React's thrown-thenable protocol, not an error. `React.use()` would say this more plainly but needs React 19.2; this package supports React 18.
+ throw never;
+}
+
+export interface FreezeProps {
+ /** While `true`, the DOM below holds whatever it last committed. */
+ frozen: boolean;
+ children?: React.ReactNode;
+}
+
+/**
+ * Holds its subtree's DOM at the last committed frame while `frozen`. Renders keep
+ * happening, they just don't reach the DOM; the pending one commits when `frozen` flips
+ * back to `false`.
+ *
+ * Use it to stop content from visibly changing under an exit animation — a popover that
+ * closes because the thing it was showing changed would otherwise swap its contents on the
+ * way out.
+ */
+export function Freeze({ frozen, children }: FreezeProps) {
+ const contentRef = React.useRef<HTMLDivElement | null>(null);
+
+ // Hold onto the node ourselves rather than reading a plain ref: hiding a boundary's children
+ // detaches their refs, so by the time the effect below runs a normal ref reads `null`.
+ const setContent = React.useCallback((node: HTMLDivElement | null) => {
+ if (node) {
+ contentRef.current = node;
+ }
+ }, []);
+
+ // React hides a suspended boundary's host children with `display: none !important`, which is
+ // the opposite of what this is for. Undo it on the commit that applies it: insertion effects
+ // run after the boundary's mutation and before paint, so the held frame never blinks out.
+ // `display: contents` is also what the wrapper renders with, so React puts it back on unfreeze
+ // and the wrapper stays out of the layout it is spliced into.
+ React.useInsertionEffect(() => {
+ if (frozen) {
+ contentRef.current?.style.setProperty('display', 'contents');
+ }
+ }, [frozen]);
+
+ return (
+ <React.Suspense fallback={null}>
+ {frozen ? <Suspend /> : null}
+ <div
+ ref={setContent}
+ style={{ display: 'contents' }}
+ >
+ {children}
+ </div>
+ </React.Suspense>
+ );
+}

packages/headless/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { cssVars } from './css-vars';
+export { Freeze, type FreezeProps } from './freeze';
 export { resetLayoutStyles } from './reset-layout-styles';
 export {
  type ComponentProps,

packages/ui/src/mosaic/components/popover/popover.test.tsx

@@ -113,7 +113,7 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- const popup = screen.getByText('Body');
+ const popup = document.querySelector('.cl-popover-popup');
  expect(popup).toHaveClass('cl-popover-popup', 'my-popup');
  expect(popup).toHaveStyle({ marginTop: '8px' });
  });
@@ -235,6 +235,6 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- expect(ref.current).toBe(screen.getByText('Body'));
+ expect(ref.current).toBe(document.querySelector('.cl-popover-popup'));
  });
 });

.changeset/popover-freeze-on-close.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/popover/README.md

@@ -105,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,72 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds state updates raised from inside the frozen subtree', () => {
+ function Counter({ count }: { count: number }) {
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter count={0} />
+ </Freeze>,
+ );
+
+ rerender(
+ <Freeze frozen>
+ <Counter count={1} />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+ });
+});

packages/headless/src/utils/freeze.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Never settles. Throwing it suspends the enclosing boundary indefinitely: React keeps
+ * rendering the subtree but holds the commit, so the DOM keeps painting its last frame.
+ */
+const never = new Promise<never>(() => {});
+
+function Suspend(): null {
+ // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspending is React's thrown-thenable protocol, not an error. `React.use()` would say this more plainly but needs React 19.2; this package supports React 18.
+ throw never;
+}
+
+export interface FreezeProps {
+ /** While `true`, the DOM below holds whatever it last committed. */
+ frozen: boolean;
+ children?: React.ReactNode;
+}
+
+/**
+ * Holds its subtree's DOM at the last committed frame while `frozen`. Renders keep
+ * happening, they just don't reach the DOM; the pending one commits when `frozen` flips
+ * back to `false`.
+ *
+ * Use it to stop content from visibly changing under an exit animation — a popover that
+ * closes because the thing it was showing changed would otherwise swap its contents on the
+ * way out.
+ */
+export function Freeze({ frozen, children }: FreezeProps) {
+ const contentRef = React.useRef<HTMLDivElement | null>(null);
+
+ // Hold onto the node ourselves rather than reading a plain ref: hiding a boundary's children
+ // detaches their refs, so by the time the effect below runs a normal ref reads `null`.
+ const setContent = React.useCallback((node: HTMLDivElement | null) => {
+ if (node) {
+ contentRef.current = node;
+ }
+ }, []);
+
+ // React hides a suspended boundary's host children with `display: none !important`, which is
+ // the opposite of what this is for. Undo it on the commit that applies it: insertion effects
+ // run after the boundary's mutation and before paint, so the held frame never blinks out.
+ // `display: contents` is also what the wrapper renders with, so React puts it back on unfreeze
+ // and the wrapper stays out of the layout it is spliced into.
+ React.useInsertionEffect(() => {
+ if (frozen) {
+ contentRef.current?.style.setProperty('display', 'contents');
+ }
+ }, [frozen]);
+
+ return (
+ <React.Suspense fallback={null}>
+ {frozen ? <Suspend /> : null}
+ <div
+ ref={setContent}
+ style={{ display: 'contents' }}
+ >
+ {children}
+ </div>
+ </React.Suspense>
+ );
+}

packages/headless/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { cssVars } from './css-vars';
+export { Freeze, type FreezeProps } from './freeze';
 export { resetLayoutStyles } from './reset-layout-styles';
 export {
  type ComponentProps,

packages/ui/src/mosaic/components/popover/popover.test.tsx

@@ -113,7 +113,7 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- const popup = screen.getByText('Body');
+ const popup = document.querySelector('.cl-popover-popup');
  expect(popup).toHaveClass('cl-popover-popup', 'my-popup');
  expect(popup).toHaveStyle({ marginTop: '8px' });
  });
@@ -235,6 +235,6 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- expect(ref.current).toBe(screen.getByText('Body'));
+ expect(ref.current).toBe(document.querySelector('.cl-popover-popup'));
  });
 });

.changeset/popover-freeze-on-close.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/popover/README.md

@@ -105,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,72 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds state updates raised from inside the frozen subtree', () => {
+ function Counter({ count }: { count: number }) {
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter count={0} />
+ </Freeze>,
+ );
+
+ rerender(
+ <Freeze frozen>
+ <Counter count={1} />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+ });
+});

packages/headless/src/utils/freeze.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Never settles. Throwing it suspends the enclosing boundary indefinitely: React keeps
+ * rendering the subtree but holds the commit, so the DOM keeps painting its last frame.
+ */
+const never = new Promise<never>(() => {});
+
+function Suspend(): null {
+ // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspending is React's thrown-thenable protocol, not an error. `React.use()` would say this more plainly but needs React 19.2; this package supports React 18.
+ throw never;
+}
+
+export interface FreezeProps {
+ /** While `true`, the DOM below holds whatever it last committed. */
+ frozen: boolean;
+ children?: React.ReactNode;
+}
+
+/**
+ * Holds its subtree's DOM at the last committed frame while `frozen`. Renders keep
+ * happening, they just don't reach the DOM; the pending one commits when `frozen` flips
+ * back to `false`.
+ *
+ * Use it to stop content from visibly changing under an exit animation — a popover that
+ * closes because the thing it was showing changed would otherwise swap its contents on the
+ * way out.
+ */
+export function Freeze({ frozen, children }: FreezeProps) {
+ const contentRef = React.useRef<HTMLDivElement | null>(null);
+
+ // Hold onto the node ourselves rather than reading a plain ref: hiding a boundary's children
+ // detaches their refs, so by the time the effect below runs a normal ref reads `null`.
+ const setContent = React.useCallback((node: HTMLDivElement | null) => {
+ if (node) {
+ contentRef.current = node;
+ }
+ }, []);
+
+ // React hides a suspended boundary's host children with `display: none !important`, which is
+ // the opposite of what this is for. Undo it on the commit that applies it: insertion effects
+ // run after the boundary's mutation and before paint, so the held frame never blinks out.
+ // `display: contents` is also what the wrapper renders with, so React puts it back on unfreeze
+ // and the wrapper stays out of the layout it is spliced into.
+ React.useInsertionEffect(() => {
+ if (frozen) {
+ contentRef.current?.style.setProperty('display', 'contents');
+ }
+ }, [frozen]);
+
+ return (
+ <React.Suspense fallback={null}>
+ {frozen ? <Suspend /> : null}
+ <div
+ ref={setContent}
+ style={{ display: 'contents' }}
+ >
+ {children}
+ </div>
+ </React.Suspense>
+ );
+}

packages/headless/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { cssVars } from './css-vars';
+export { Freeze, type FreezeProps } from './freeze';
 export { resetLayoutStyles } from './reset-layout-styles';
 export {
  type ComponentProps,

packages/ui/src/mosaic/components/popover/popover.test.tsx

@@ -113,7 +113,7 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- const popup = screen.getByText('Body');
+ const popup = document.querySelector('.cl-popover-popup');
  expect(popup).toHaveClass('cl-popover-popup', 'my-popup');
  expect(popup).toHaveStyle({ marginTop: '8px' });
  });
@@ -235,6 +235,6 @@ describe('Mosaic Popover', () => {
  </Popover.Root>,
  );
 
- expect(ref.current).toBe(screen.getByText('Body'));
+ expect(ref.current).toBe(document.querySelector('.cl-popover-popup'));
  });
 });