[popups] onOpenChangeComplete prop

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."
+    },
+    "onOpenChangeComplete": {
+      "type": "(open) => void",
+      "description": "Event handler called after any animations complete when the dialog is opened or 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."
+    },
+    "onOpenChangeComplete": {
+      "type": "(open) => void",
+      "description": "Event handler called after any animations complete when the dialog is opened or 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."
     },
+    "onOpenChangeComplete": {
+      "type": "(open) => void",
+      "description": "Event handler called after any animations complete when the menu is opened or 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."
     },
+    "onOpenChangeComplete": {
+      "type": "(open) => void",
+      "description": "Event handler called after any animations complete when the popover is opened or 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."
     },
+    "onOpenChangeComplete": {
+      "type": "(open) => void",
+      "description": "Event handler called after any animations complete when the preview card is opened or 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."
     },
+    "onOpenChangeComplete": {
+      "type": "(open) => void",
+      "description": "Event handler called after any animations complete when the select menu is opened or 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."
     },
+    "onOpenChangeComplete": {
+      "type": "(open) => void",
+      "description": "Event handler called after any animations complete when the tooltip is opened or closed."
+    },
     "trackCursorAxis": {
       "type": "'none' | 'x' | 'y' | 'both'",
       "default": "'none'",

docs/reference/overrides/common.json

@@ -24,6 +24,9 @@
     "onClick": {
       "type": "(event) => void"
     },
+    "onOpenChangeComplete": {
+      "type": "(open) => void"
+    },
     "render": {
       "type": "React.ReactElement | (props, state) => React.ReactElement"
     }

packages/react/src/alert-dialog/popup/AlertDialogPopup.tsx

@@ -16,6 +16,7 @@ import { transitionStatusMapping } from '../../utils/styleHookMapping';
 import { AlertDialogPopupDataAttributes } from './AlertDialogPopupDataAttributes';
 import { InternalBackdrop } from '../../utils/InternalBackdrop';
 import { useAlertDialogPortalContext } from '../portal/AlertDialogPortalContext';
+import { useOpenChangeComplete } from '../../utils/useOpenChangeComplete';
 
 const customStyleHookMapping: CustomStyleHookMapping<AlertDialogPopup.State> = {
   ...baseMapping,
@@ -53,11 +54,21 @@ const AlertDialogPopup = React.forwardRef(function AlertDialogPopup(
     titleElementId,
     transitionStatus,
     modal,
+    onOpenChangeComplete,
     internalBackdropRef,
   } = useAlertDialogRootContext();
 
   useAlertDialogPortalContext();
 
+  useOpenChangeComplete({
+    open,
+    ref: popupRef,
+    change: 'open',
+    onComplete() {
+      onOpenChangeComplete?.(true);
+    },
+  });
+
   const mergedRef = useForkRef(forwardedRef, popupRef);
 
   const { getRootProps, resolvedInitialFocus } = useDialogPopup({

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

@@ -1,13 +1,17 @@
 import * as React from 'react';
 import { expect } from 'chai';
-import { screen } from '@mui/internal-test-utils';
+import { screen, waitFor } from '@mui/internal-test-utils';
 import { AlertDialog } from '@base-ui-components/react/alert-dialog';
 import { createRenderer, isJSDOM } from '#test-utils';
 import { spy } from 'sinon';
 
 describe('<AlertDialog.Root />', () => {
   const { render } = createRenderer();
 
+  beforeEach(() => {
+    globalThis.BASE_UI_ANIMATIONS_DISABLED = true;
+  });
+
   it('ARIA attributes', async () => {
     const { queryByRole, getByText } = await render(
       <AlertDialog.Root open>
@@ -128,4 +132,170 @@ describe('<AlertDialog.Root />', () => {
       expect(screen.getByRole('presentation', { hidden: true })).not.to.equal(null);
     });
   });
+
+  describe.skipIf(isJSDOM)('prop: onOpenChangeComplete', () => {
+    it('is called on close when there is no exit animation defined', async () => {
+      const onOpenChangeComplete = spy();
+
+      function Test() {
+        const [open, setOpen] = React.useState(true);
+        return (
+          <div>
+            <button onClick={() => setOpen(false)}>Close</button>
+            <AlertDialog.Root open={open} onOpenChangeComplete={onOpenChangeComplete}>
+              <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(onOpenChangeComplete.firstCall.args[0]).to.equal(true);
+      expect(onOpenChangeComplete.lastCall.args[0]).to.equal(false);
+    });
+
+    it('is called on close when the exit animation finishes', async () => {
+      globalThis.BASE_UI_ANIMATIONS_DISABLED = false;
+
+      const onOpenChangeComplete = spy();
+
+      function Test() {
+        const style = `
+          @keyframes test-anim {
+            to {
+              opacity: 0;
+            }
+          }
+
+          .animation-test-indicator[data-ending-style] {
+            animation: test-anim 1ms;
+          }
+        `;
+
+        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} onOpenChangeComplete={onOpenChangeComplete}>
+              <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);
+
+      // Wait for open animation to finish
+      await waitFor(() => {
+        expect(onOpenChangeComplete.firstCall.args[0]).to.equal(true);
+      });
+
+      const closeButton = screen.getByText('Close');
+      await user.click(closeButton);
+
+      await waitFor(() => {
+        expect(screen.queryByTestId('popup')).to.equal(null);
+      });
+
+      expect(onOpenChangeComplete.lastCall.args[0]).to.equal(false);
+    });
+
+    it('is called on open when there is no enter animation defined', async () => {
+      const onOpenChangeComplete = spy();
+
+      function Test() {
+        const [open, setOpen] = React.useState(false);
+        return (
+          <div>
+            <button onClick={() => setOpen(true)}>Open</button>
+            <AlertDialog.Root open={open} onOpenChangeComplete={onOpenChangeComplete}>
+              <AlertDialog.Portal>
+                <AlertDialog.Popup data-testid="popup" />
+              </AlertDialog.Portal>
+            </AlertDialog.Root>
+          </div>
+        );
+      }
+
+      const { user } = await render(<Test />);
+
+      const openButton = screen.getByText('Open');
+      await user.click(openButton);
+
+      await waitFor(() => {
+        expect(screen.queryByTestId('popup')).not.to.equal(null);
+      });
+
+      expect(onOpenChangeComplete.callCount).to.equal(2);
+      expect(onOpenChangeComplete.firstCall.args[0]).to.equal(true);
+    });
+
+    it('is called on open when the enter animation finishes', async () => {
+      globalThis.BASE_UI_ANIMATIONS_DISABLED = false;
+
+      const onOpenChangeComplete = spy();
+
+      function Test() {
+        const style = `
+          @keyframes test-anim {
+            from {
+              opacity: 0;
+            }
+          }
+
+          .animation-test-indicator[data-starting-style] {
+            animation: test-anim 1ms;
+          }
+        `;
+
+        const [open, setOpen] = React.useState(false);
+
+        return (
+          <div>
+            {/* eslint-disable-next-line react/no-danger */}
+            <style dangerouslySetInnerHTML={{ __html: style }} />
+            <button onClick={() => setOpen(true)}>Open</button>
+            <AlertDialog.Root
+              open={open}
+              onOpenChange={setOpen}
+              onOpenChangeComplete={onOpenChangeComplete}
+            >
+              <AlertDialog.Portal>
+                <AlertDialog.Popup className="animation-test-indicator" data-testid="popup" />
+              </AlertDialog.Portal>
+            </AlertDialog.Root>
+          </div>
+        );
+      }
+
+      const { user } = await render(<Test />);
+
+      const openButton = screen.getByText('Open');
+      await user.click(openButton);
+
+      // Wait for open animation to finish
+      await waitFor(() => {
+        expect(onOpenChangeComplete.firstCall.args[0]).to.equal(true);
+      });
+
+      expect(screen.queryByTestId('popup')).not.to.equal(null);
+    });
+  });
 });

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, onOpenChangeComplete } = props;
 
   const parentDialogRootContext = React.useContext(AlertDialogRootContext);
 
   const dialogRoot = useDialogRoot({
     open,
     defaultOpen,
     onOpenChange,
+    onOpenChangeComplete,
     modal: true,
     dismissible: false,
     onNestedDialogClose: parentDialogRootContext?.onNestedDialogClose,
@@ -29,8 +30,12 @@ const AlertDialogRoot: React.FC<AlertDialogRoot.Props> = function AlertDialogRoo
   const nested = Boolean(parentDialogRootContext);
 
   const contextValue: AlertDialogRootContext = React.useMemo(
-    () => ({ ...dialogRoot, nested }),
-    [dialogRoot, nested],
+    () => ({
+      ...dialogRoot,
+      nested,
+      onOpenChangeComplete,
+    }),
+    [dialogRoot, nested, onOpenChangeComplete],
   );
 
   return (
@@ -60,6 +65,10 @@ AlertDialogRoot.propTypes /* remove-proptypes */ = {
    * @default false
    */
   defaultOpen: PropTypes.bool,
+  /**
+   * Event handler called after any animations complete when the dialog is opened or closed.
+   */
+  onOpenChangeComplete: PropTypes.func,
   /**
    * Event handler called when the dialog is opened or closed.
    */

packages/react/src/checkbox/indicator/CheckboxIndicator.test.tsx

@@ -147,7 +147,7 @@ describe('<Checkbox.Indicator />', () => {
         }
 
         .animation-test-indicator[data-ending-style] {
-          animation: test-anim 50ms;
+          animation: test-anim 1ms;
         }
       `;
 

packages/react/src/checkbox/indicator/CheckboxIndicator.tsx

@@ -6,7 +6,7 @@ import { useComponentRenderer } from '../../utils/useComponentRenderer';
 import { useCustomStyleHookMapping } from '../utils/useCustomStyleHookMapping';
 import type { CheckboxRoot } from '../root/CheckboxRoot';
 import type { BaseUIComponentProps } from '../../utils/types';
-import { useAfterExitAnimation } from '../../utils/useAfterExitAnimation';
+import { useOpenChangeComplete } from '../../utils/useOpenChangeComplete';
 import { type TransitionStatus, useTransitionStatus } from '../../utils/useTransitionStatus';
 import { useForkRef } from '../../utils/useForkRef';
 import type { CustomStyleHookMapping } from '../../utils/getStyleHookProps';
@@ -41,10 +41,10 @@ const CheckboxIndicator = React.forwardRef(function CheckboxIndicator(
     [rootState, transitionStatus],
   );
 
-  useAfterExitAnimation({
+  useOpenChangeComplete({
     open: rendered,
-    animatedElementRef: indicatorRef,
-    onFinished() {
+    ref: indicatorRef,
+    onComplete() {
       setMounted(false);
     },
   });