[popups] Add onCloseComplete callback

docs/reference/generated/alert-dialog-root.json

@@ -14,6 +14,10 @@
     "onOpenChange": {
       "type": "(open, event, reason) => void",
       "description": "Event handler called when the dialog is opened or closed."
+    },
+    "onCloseComplete": {
+      "type": "function",
+      "description": "Event handler called after any exit animations finish when the dialog is closed."
     }
   },
   "dataAttributes": {},

docs/reference/generated/dialog-root.json

@@ -24,6 +24,10 @@
       "type": "boolean",
       "default": "true",
       "description": "Whether the dialog should prevent outside clicks and lock page scroll when open."
+    },
+    "onCloseComplete": {
+      "type": "function",
+      "description": "Event handler called after any exit animations finish when the dialog is closed."
     }
   },
   "dataAttributes": {},

docs/reference/generated/menu-root.json

@@ -25,6 +25,10 @@
       "default": "true",
       "description": "Whether the menu should prevent outside clicks and lock page scroll when open."
     },
+    "onCloseComplete": {
+      "type": "function",
+      "description": "Event handler called after any exit animations finish when the menu is closed."
+    },
     "disabled": {
       "type": "boolean",
       "default": "false",

docs/reference/generated/popover-root.json

@@ -15,6 +15,10 @@
       "type": "(open, event, reason) => void",
       "description": "Event handler called when the popover is opened or closed."
     },
+    "onCloseComplete": {
+      "type": "function",
+      "description": "Event handler called after any exit animations finish when the popover is closed."
+    },
     "openOnHover": {
       "type": "boolean",
       "default": "false",

docs/reference/generated/preview-card-root.json

@@ -15,6 +15,10 @@
       "type": "(open, event, reason) => void",
       "description": "Event handler called when the preview card is opened or closed."
     },
+    "onCloseComplete": {
+      "type": "function",
+      "description": "Event handler called after any exit animations finish when the preview card is closed."
+    },
     "delay": {
       "type": "number",
       "default": "600",

docs/reference/generated/select-root.json

@@ -42,6 +42,10 @@
       "default": "true",
       "description": "Whether the select should prevent outside clicks and lock page scroll when open."
     },
+    "onCloseComplete": {
+      "type": "function",
+      "description": "Event handler called after any exit animations finish when the select menu is closed."
+    },
     "disabled": {
       "type": "boolean",
       "default": "false",

docs/reference/generated/tooltip-root.json

@@ -15,6 +15,10 @@
       "type": "(open, event, reason) => void",
       "description": "Event handler called when the tooltip is opened or closed."
     },
+    "onCloseComplete": {
+      "type": "function",
+      "description": "Event handler called after any exit animations finish when the tooltip is closed."
+    },
     "trackCursorAxis": {
       "type": "'none' | 'x' | 'y' | 'both'",
       "default": "'none'",

packages/react/src/alert-dialog/root/AlertDialogRoot.test.tsx

@@ -134,4 +134,89 @@ describe('<AlertDialog.Root />', () => {
       });
     });
   });
+
+  describeSkipIf(isJSDOM)('prop: onCloseComplete', () => {
+    it('is called on close when there is no exit animation defined', async () => {
+      let onCloseCompleteCalled = false;
+      function notifyonCloseComplete() {
+        onCloseCompleteCalled = true;
+      }
+
+      function Test() {
+        const [open, setOpen] = React.useState(true);
+        return (
+          <div>
+            <button onClick={() => setOpen(false)}>Close</button>
+            <AlertDialog.Root open={open} onCloseComplete={notifyonCloseComplete}>
+              <AlertDialog.Portal>
+                <AlertDialog.Popup data-testid="popup" />
+              </AlertDialog.Portal>
+            </AlertDialog.Root>
+          </div>
+        );
+      }
+
+      const { user } = await render(<Test />);
+
+      const closeButton = screen.getByText('Close');
+      await user.click(closeButton);
+
+      await waitFor(() => {
+        expect(screen.queryByTestId('popup')).to.equal(null);
+      });
+
+      expect(onCloseCompleteCalled).to.equal(true);
+    });
+
+    it('is called on close when the exit animation finishes', async () => {
+      (globalThis as any).BASE_UI_ANIMATIONS_DISABLED = false;
+
+      let onCloseCompleteCalled = false;
+      function notifyonCloseComplete() {
+        onCloseCompleteCalled = true;
+      }
+
+      function Test() {
+        const style = `
+            @keyframes test-anim {
+              to {
+                opacity: 0;
+              }
+            }
+
+            .animation-test-indicator[data-ending-style] {
+              animation: test-anim 50ms;
+            }
+          `;
+
+        const [open, setOpen] = React.useState(true);
+
+        return (
+          <div>
+            {/* eslint-disable-next-line react/no-danger */}
+            <style dangerouslySetInnerHTML={{ __html: style }} />
+            <button onClick={() => setOpen(false)}>Close</button>
+            <AlertDialog.Root open={open} onCloseComplete={notifyonCloseComplete}>
+              <AlertDialog.Portal>
+                <AlertDialog.Popup className="animation-test-indicator" data-testid="popup" />
+              </AlertDialog.Portal>
+            </AlertDialog.Root>
+          </div>
+        );
+      }
+
+      const { user } = await render(<Test />);
+
+      expect(screen.getByTestId('popup')).not.to.equal(null);
+
+      const closeButton = screen.getByText('Close');
+      await user.click(closeButton);
+
+      await waitFor(() => {
+        expect(screen.queryByTestId('popup')).to.equal(null);
+      });
+
+      expect(onCloseCompleteCalled).to.equal(true);
+    });
+  });
 });

packages/react/src/alert-dialog/root/AlertDialogRoot.tsx

@@ -12,14 +12,15 @@ import { useDialogRoot } from '../../dialog/root/useDialogRoot';
  * Documentation: [Base UI Alert Dialog](https://base-ui.com/react/components/alert-dialog)
  */
 const AlertDialogRoot: React.FC<AlertDialogRoot.Props> = function AlertDialogRoot(props) {
-  const { children, defaultOpen = false, onOpenChange, open } = props;
+  const { children, defaultOpen = false, onOpenChange, open, onCloseComplete } = props;
 
   const parentDialogRootContext = React.useContext(AlertDialogRootContext);
 
   const dialogRoot = useDialogRoot({
     open,
     defaultOpen,
     onOpenChange,
+    onCloseComplete,
     modal: true,
     dismissible: false,
     onNestedDialogClose: parentDialogRootContext?.onNestedDialogClose,
@@ -60,6 +61,10 @@ AlertDialogRoot.propTypes /* remove-proptypes */ = {
    * @default false
    */
   defaultOpen: PropTypes.bool,
+  /**
+   * Event handler called after any exit animations finish when the dialog is closed.
+   */
+  onCloseComplete: PropTypes.func,
   /**
    * Event handler called when the dialog is opened or closed.
    */

packages/react/src/dialog/root/DialogRoot.test.tsx

@@ -592,4 +592,89 @@ describe('<Dialog.Root />', () => {
       });
     });
   });
+
+  describeSkipIf(isJSDOM)('prop: onCloseComplete', () => {
+    it('is called on close when there is no exit animation defined', async () => {
+      let onCloseCompleteCalled = false;
+      function notifyonCloseComplete() {
+        onCloseCompleteCalled = true;
+      }
+
+      function Test() {
+        const [open, setOpen] = React.useState(true);
+        return (
+          <div>
+            <button onClick={() => setOpen(false)}>Close</button>
+            <Dialog.Root open={open} onCloseComplete={notifyonCloseComplete}>
+              <Dialog.Portal>
+                <Dialog.Popup data-testid="popup" />
+              </Dialog.Portal>
+            </Dialog.Root>
+          </div>
+        );
+      }
+
+      const { user } = await render(<Test />);
+
+      const closeButton = screen.getByText('Close');
+      await user.click(closeButton);
+
+      await waitFor(() => {
+        expect(screen.queryByTestId('popup')).to.equal(null);
+      });
+
+      expect(onCloseCompleteCalled).to.equal(true);
+    });
+
+    it('is called on close when the exit animation finishes', async () => {
+      (globalThis as any).BASE_UI_ANIMATIONS_DISABLED = false;
+
+      let onCloseCompleteCalled = false;
+      function notifyonCloseComplete() {
+        onCloseCompleteCalled = true;
+      }
+
+      function Test() {
+        const style = `
+          @keyframes test-anim {
+            to {
+              opacity: 0;
+            }
+          }
+
+          .animation-test-indicator[data-ending-style] {
+            animation: test-anim 50ms;
+          }
+        `;
+
+        const [open, setOpen] = React.useState(true);
+
+        return (
+          <div>
+            {/* eslint-disable-next-line react/no-danger */}
+            <style dangerouslySetInnerHTML={{ __html: style }} />
+            <button onClick={() => setOpen(false)}>Close</button>
+            <Dialog.Root open={open} onCloseComplete={notifyonCloseComplete}>
+              <Dialog.Portal>
+                <Dialog.Popup className="animation-test-indicator" data-testid="popup" />
+              </Dialog.Portal>
+            </Dialog.Root>
+          </div>
+        );
+      }
+
+      const { user } = await render(<Test />);
+
+      expect(screen.getByTestId('popup')).not.to.equal(null);
+
+      const closeButton = screen.getByText('Close');
+      await user.click(closeButton);
+
+      await waitFor(() => {
+        expect(screen.queryByTestId('popup')).to.equal(null);
+      });
+
+      expect(onCloseCompleteCalled).to.equal(true);
+    });
+  });
 });

packages/react/src/dialog/root/DialogRoot.tsx

@@ -19,6 +19,7 @@ const DialogRoot = function DialogRoot(props: DialogRoot.Props) {
     modal = true,
     onOpenChange,
     open,
+    onCloseComplete,
   } = props;
 
   const parentDialogRootContext = useOptionalDialogRootContext();
@@ -29,6 +30,7 @@ const DialogRoot = function DialogRoot(props: DialogRoot.Props) {
     onOpenChange,
     modal,
     dismissible,
+    onCloseComplete,
     onNestedDialogClose: parentDialogRootContext?.onNestedDialogClose,
     onNestedDialogOpen: parentDialogRootContext?.onNestedDialogOpen,
   });
@@ -79,6 +81,10 @@ DialogRoot.propTypes /* remove-proptypes */ = {
    * @default true
    */
   modal: PropTypes.bool,
+  /**
+   * Event handler called after any exit animations finish when the dialog is closed.
+   */
+  onCloseComplete: PropTypes.func,
   /**
    * Event handler called when the dialog is opened or closed.
    */

packages/react/src/dialog/root/useDialogRoot.ts

@@ -30,6 +30,7 @@ export function useDialogRoot(params: useDialogRoot.Parameters): useDialogRoot.R
     onNestedDialogOpen,
     onOpenChange: onOpenChangeParameter,
     open: openParam,
+    onCloseComplete,
   } = params;
 
   const [open, setOpenUnwrapped] = useControlled({
@@ -61,7 +62,10 @@ export function useDialogRoot(params: useDialogRoot.Parameters): useDialogRoot.R
   useAfterExitAnimation({
     open,
     animatedElementRef: popupRef,
-    onFinished: () => setMounted(false),
+    onFinished() {
+      setMounted(false);
+      onCloseComplete?.();
+    },
   });
 
   const handleFloatingUIOpenChange = (
@@ -188,6 +192,10 @@ export interface SharedParameters {
     event: Event | undefined,
     reason: OpenChangeReason | undefined,
   ) => void;
+  /**
+   * Event handler called after any exit animations finish when the dialog is closed.
+   */
+  onCloseComplete?: () => void;
   /**
    * Determines whether the dialog should close on outside clicks.
    * @default true
@@ -196,7 +204,8 @@ export interface SharedParameters {
 }
 
 export namespace useDialogRoot {
-  export interface Parameters extends RequiredExcept<SharedParameters, 'open' | 'onOpenChange'> {
+  export interface Parameters
+    extends RequiredExcept<SharedParameters, 'open' | 'onOpenChange' | 'onCloseComplete'> {
     /**
      * Callback to invoke when a nested dialog is opened.
      */