feat(ui): Origin-aware open/close animations for popover menus and selects

.changeset/popover-enter-exit-animations.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Popover-based surfaces now open and close with an origin-aware scale-and-fade that grows from the edge nearest the trigger, replacing the previous entrance-only slide animation. This covers the `<OrganizationSwitcher />` / `<UserButton />` menus, the overflow (⋯) menus, and selects — menus keep a quick-in / soft-out feel while selects use a quicker exit. Motion is disabled when `appearance.animations` is `false` or the user prefers reduced motion.

integration/tests/custom-pages.test.ts

@@ -405,14 +405,19 @@ testAgainstRunningApps({ withPattern: ['react.vite.withEmailCodes'] })(
         const notificationsButton = buttons[2];
         const languageButton = buttons[3];
 
+        // Clicking an action closes the popover, which now plays an exit animation and stays
+        // mounted until it finishes — wait for it to fully close before re-opening, otherwise
+        // the re-open races the still-visible exiting popover.
         // Test chat toggle
         await chatButton.click();
+        await u.po.userButton.waitForPopoverClosed();
         await u.po.userButton.toggleTrigger();
         await u.po.userButton.waitForPopover();
         await expect(chatButton).toHaveText('🌐Chat is ON');
         await expect(languageButton).toHaveText('🌍Language: EN');
 
         await notificationsButton.click();
+        await u.po.userButton.waitForPopoverClosed();
         await u.po.userButton.toggleTrigger();
         await u.po.userButton.waitForPopover();
         await expect(notificationsButton).toHaveText('🌐Notifications 🔔 ON');
@@ -460,14 +465,19 @@ testAgainstRunningApps({ withPattern: ['react.vite.withEmailCodes'] })(
         const languageButton = buttons[3];
         const manageAccountButton = buttons[4];
 
+        // Clicking an action closes the popover, which now plays an exit animation and stays
+        // mounted until it finishes — wait for it to fully close before re-opening, otherwise
+        // the re-open races the still-visible exiting popover.
         // Test chat toggle
         await chatButton.click();
+        await u.po.userButton.waitForPopoverClosed();
         await u.po.userButton.toggleTrigger();
         await u.po.userButton.waitForPopover();
         await expect(chatButton).toHaveText('🌐Chat is ON');
         await expect(languageButton).toHaveText('🌍Language: EN');
 
         await notificationsButton.click();
+        await u.po.userButton.waitForPopoverClosed();
         await u.po.userButton.toggleTrigger();
         await u.po.userButton.waitForPopover();
         await expect(notificationsButton).toHaveText('🌐Notifications 🔔 ON');
@@ -508,6 +518,10 @@ testAgainstRunningApps({ withPattern: ['react.vite.withEmailCodes'] })(
         await expect(toggleButton.locator('span')).toHaveText('🔔');
         await toggleButton.click();
 
+        // The action closes the popover with an exit animation that keeps it mounted until it
+        // finishes; wait for the full close so the re-open doesn't race the exiting popover.
+        await u.po.userButton.waitForPopoverClosed();
+
         // Re-open menu to see updated items
         await u.po.userButton.toggleTrigger();
         await u.po.userButton.waitForPopover();

packages/testing/src/playwright/unstable/page-objects/apiKeys.ts

@@ -61,7 +61,10 @@ export const createAPIKeysComponentPageObject = (testArgs: { page: EnhancedPage
       return page.getByLabel(/Type "Revoke" to confirm/i).fill(value);
     },
     clickConfirmRevokeButton: () => {
-      return page.getByText(/Revoke key/i).click();
+      // Target the modal's submit button by its descriptor class rather than by text: the menu
+      // action that opens this modal is also labelled "Revoke key", and it now lingers through an
+      // exit animation, so a text locator transiently matches both (strict-mode violation).
+      return page.locator('.cl-apiKeysRevokeModal .cl-apiKeysRevokeModalSubmitButton').click();
     },
   };
   return self;

packages/ui/bundlewatch.config.json

@@ -5,7 +5,7 @@
     { "path": "./dist/ui.shared.browser.js", "maxSize": "40KB" },
     { "path": "./dist/framework*.js", "maxSize": "44KB" },
     { "path": "./dist/vendors*.js", "maxSize": "73KB" },
-    { "path": "./dist/ui-common*.js", "maxSize": "130KB" },
+    { "path": "./dist/ui-common*.js", "maxSize": "132KB" },
     { "path": "./dist/signin*.js", "maxSize": "17KB" },
     { "path": "./dist/signup*.js", "maxSize": "13KB" },
     { "path": "./dist/userprofile*.js", "maxSize": "16KB" },

packages/ui/src/components/OrganizationSwitcher/OrganizationSwitcherPopover.tsx

@@ -23,7 +23,6 @@ export const OrganizationSwitcherPopover = React.forwardRef<HTMLDivElement, Orga
     const { close: unsafeClose, ...rest } = props;
     const close = () => unsafeClose?.(false);
     const card = useCardState();
-    const { __experimental_asStandalone } = useOrganizationSwitcherContext();
     const { openOrganizationProfile, openCreateOrganization } = useClerk();
     const getContainer = usePortalRoot();
     const { organization: currentOrg } = useOrganization();
@@ -138,7 +137,6 @@ export const OrganizationSwitcherPopover = React.forwardRef<HTMLDivElement, Orga
           ref={ref}
           role='dialog'
           aria-label={`${currentOrg?.name} is active`}
-          shouldEntryAnimate={!__experimental_asStandalone}
           {...rest}
         >
           <PopoverCard.Content elementDescriptor={descriptors.organizationSwitcherPopoverMain}>

packages/ui/src/components/OrganizationSwitcher/index.tsx

@@ -42,7 +42,7 @@ const OrganizationSwitcherWithFloatingTree = withFloatingTree<{ children: ReactE
       <Popover
         nodeId={nodeId}
         context={context}
-        isOpen={isOpen}
+        animateExit
         order={['content']}
         initialFocus={popoverRef}
       >

packages/ui/src/components/UserButton/UserButtonPopover.tsx

@@ -19,7 +19,6 @@ export const UserButtonPopover = React.forwardRef<HTMLDivElement, UserButtonPopo
   const close = () => unsafeClose?.(false);
   const { session } = useSession() as { session: SignedInSessionResource };
   const userButtonContext = useUserButtonContext();
-  const { __experimental_asStandalone } = userButtonContext;
   const { authConfig } = useEnvironment();
   const { user } = useUser();
   const { t } = useLocalizations();
@@ -40,7 +39,6 @@ export const UserButtonPopover = React.forwardRef<HTMLDivElement, UserButtonPopo
         ref={ref}
         role='dialog'
         aria-label={t(localizationKeys('userButton.label__userButtonPopover'))}
-        shouldEntryAnimate={!__experimental_asStandalone}
         {...rest}
       >
         <PopoverCard.Content elementDescriptor={descriptors.userButtonPopoverMain}>

packages/ui/src/components/UserButton/index.tsx

@@ -41,7 +41,7 @@ const UserButtonWithFloatingTree = withFloatingTree<{ children: ReactElement }>(
       <Popover
         nodeId={nodeId}
         context={context}
-        isOpen={isOpen}
+        animateExit
         order={['content']}
         initialFocus={popoverRef}
       >

packages/ui/src/elements/Menu.tsx

@@ -18,7 +18,6 @@ import { Col, descriptors, SimpleButton } from '../customizables';
 import type { UsePopoverReturn } from '../hooks';
 import { usePopover } from '../hooks';
 import type { PropsOfComponent } from '../styledSystem';
-import { animations } from '../styledSystem';
 import { colors } from '../utils/colors';
 import { withFloatingTree } from './contexts';
 import { Popover } from './Popover';
@@ -124,20 +123,24 @@ type MenuListProps = PropsOfComponent<typeof Col> & {
 export const MenuList = (props: MenuListProps) => {
   const { sx, asPortal, ...rest } = props;
   const { popoverCtx, elementId, getFloatingProps, elementsRef } = useMenuState();
-  const { floating, styles, isOpen, context, nodeId } = popoverCtx;
+  const { floating, styles, context, nodeId } = popoverCtx;
   const containerRef = useRef<HTMLDivElement | null>(null);
   const mergedRef = useMergeRefs([containerRef, floating]);
 
+  // `FloatingList` only provides list-navigation context (no DOM), so it wraps the `Popover`
+  // rather than nesting inside it — that keeps the `Col` as the `Popover`'s direct child, which is
+  // the element the `animateExit` transition (origin-aware scale + fade) is applied to.
   return (
-    <Popover
-      context={context}
-      nodeId={nodeId}
-      isOpen={isOpen}
-      portal={asPortal}
-      order={['content']}
-      modal={false}
-    >
-      <FloatingList elementsRef={elementsRef}>
+    <FloatingList elementsRef={elementsRef}>
+      <Popover
+        context={context}
+        nodeId={nodeId}
+        animateExit
+        initialScale={0.88}
+        portal={asPortal}
+        order={['content']}
+        modal={false}
+      >
         <Col
           elementDescriptor={descriptors.menuList}
           elementId={descriptors.menuList.setId(elementId)}
@@ -153,8 +156,6 @@ export const MenuList = (props: MenuListProps) => {
               padding: t.space.$0x5,
               overflow: 'hidden',
               top: `calc(100% + ${t.space.$2})`,
-              animation: `${animations.dropdownSlideInScaleAndFade} ${t.transitionDuration.$slower} ${t.transitionTiming.$slowBezier}`,
-              transformOrigin: 'top center',
               zIndex: t.zIndices.$dropdown,
               gap: t.space.$0x5,
             }),
@@ -164,8 +165,8 @@ export const MenuList = (props: MenuListProps) => {
           {...getFloatingProps()}
           {...rest}
         />
-      </FloatingList>
-    </Popover>
+      </Popover>
+    </FloatingList>
   );
 };
 

packages/ui/src/elements/PhoneInput/index.tsx

@@ -145,6 +145,7 @@ const PhoneInputBase = forwardRef<HTMLInputElement, PhoneInputProps & { feedback
           </Text>
         </SelectButton>
         <SelectOptionList
+          initialScale={0.96}
           sx={{ padding: '0 0' }}
           containerSx={theme => ({
             gap: 0,

packages/ui/src/elements/Popover.tsx

@@ -1,14 +1,38 @@
 import { usePortalRoot } from '@clerk/shared/react';
 import type { FloatingContext, ReferenceType } from '@floating-ui/react';
-import { FloatingFocusManager, FloatingNode, FloatingPortal } from '@floating-ui/react';
+import { FloatingFocusManager, FloatingNode, FloatingPortal, useTransitionStyles } from '@floating-ui/react';
 import type { PropsWithChildren } from 'react';
 import React from 'react';
 
+import { useAppearance } from '../customizables';
+import { transitionDurationValues, transitionTiming } from '../foundations/transitions';
+import { useDirection, usePrefersReducedMotion } from '../hooks';
+
 type PopoverProps = PropsWithChildren<{
   context: FloatingContext<ReferenceType>;
   nodeId?: string;
   isOpen?: boolean;
   initialFocus?: number | React.MutableRefObject<HTMLElement | null>;
+  /**
+   * When `true`, the popover animates in on mount with an origin-aware scale + fade and stays
+   * mounted through a matching fade-out on close, instead of appearing/unmounting instantly.
+   * Opt-in so other consumers keep their current instant behavior.
+   * @default false
+   */
+  animateExit?: boolean;
+  /**
+   * When `animateExit` is set, exits quickly (`$faster`, matching the entrance) instead of the
+   * default soft exit (`$slower`). The entrance is always `$faster`.
+   * @default false
+   */
+  exitFast?: boolean;
+  /**
+   * The scale the popover animates from on enter (and collapses to on exit) when `animateExit`
+   * is set. Scale is proportional, so compact surfaces travel fewer pixels — lower this
+   * (e.g. `0.92`) to give small popovers like menus a more pronounced motion.
+   * @default 0.96
+   */
+  initialScale?: number;
   /**
    * Determines whether outside elements are inert when modal is enabled. This enables pointer modality without a backdrop.
    * @default false
@@ -30,6 +54,27 @@ type PopoverProps = PropsWithChildren<{
   root?: HTMLElement | React.MutableRefObject<HTMLElement | null>;
 }>;
 
+/**
+ * Maps a resolved Floating UI placement to a `transform-origin` so the popover grows from the
+ * point nearest its trigger. The primary axis anchors to the edge opposite the `side`; when the
+ * placement is aligned to a corner (`-start` / `-end`) the cross axis hugs that corner, otherwise
+ * it stays centered. Horizontal alignment is mirrored under RTL to match Floating UI's
+ * direction-aware resolved position.
+ */
+const getTransformOrigin = (placement: string, direction: 'ltr' | 'rtl'): string => {
+  const [side, alignment] = placement.split('-');
+  if (side === 'top' || side === 'bottom') {
+    const y = side === 'top' ? 'bottom' : 'top';
+    const start = direction === 'rtl' ? 'right' : 'left';
+    const end = direction === 'rtl' ? 'left' : 'right';
+    const x = alignment === 'start' ? start : alignment === 'end' ? end : 'center';
+    return `${x} ${y}`;
+  }
+  const x = side === 'left' ? 'right' : 'left';
+  const y = alignment === 'start' ? 'top' : alignment === 'end' ? 'bottom' : 'center';
+  return `${x} ${y}`;
+};
+
 export const Popover = (props: PopoverProps) => {
   const {
     context,
@@ -39,6 +84,9 @@ export const Popover = (props: PopoverProps) => {
     modal = true,
     nodeId,
     isOpen,
+    animateExit = false,
+    exitFast = false,
+    initialScale = 0.96,
     portal = true,
     root,
     children,
@@ -47,19 +95,53 @@ export const Popover = (props: PopoverProps) => {
   const portalRoot = usePortalRoot();
   const effectiveRoot = root ?? portalRoot?.() ?? undefined;
 
+  const prefersReducedMotion = usePrefersReducedMotion();
+  const direction = useDirection();
+  const { animations: layoutAnimations } = useAppearance().parsedOptions;
+  const isMotionSafe = !prefersReducedMotion && layoutAnimations === true;
+  const animate = animateExit && isMotionSafe;
+  const closeDuration = exitFast ? transitionDurationValues.faster : transitionDurationValues.slower;
+
+  // Animate in on mount and out on close with an origin-aware scale + fade. Keeping the element
+  // mounted through the close transition (via `isMounted`) is what makes the exit animation
+  // possible. `transformOrigin` is derived from the resolved placement so the popover grows from
+  // the point nearest its trigger — the aligned corner when present, otherwise the edge center.
+  const { isMounted, styles: transitionStyles } = useTransitionStyles(context, {
+    duration: {
+      open: animate ? transitionDurationValues.faster : 0,
+      close: animate ? closeDuration : 0,
+    },
+    common: ({ placement }) => ({
+      transformOrigin: getTransformOrigin(placement, direction),
+      transitionTimingFunction: transitionTiming.swiftOut,
+    }),
+    initial: { opacity: animate ? 0 : 1, transform: animate ? `scale(${initialScale})` : 'scale(1)' },
+    open: { opacity: 1, transform: 'scale(1)' },
+    close: { opacity: animate ? 0 : 1, transform: animate ? `scale(${initialScale})` : 'scale(1)' },
+  });
+
+  // Non-animating consumers keep the original synchronous `isOpen` unmount.
+  const shouldRender = animateExit ? isMounted : isOpen;
+  const content =
+    animateExit && React.isValidElement<{ style?: React.CSSProperties }>(children)
+      ? React.cloneElement(children, {
+          style: { ...children.props.style, ...transitionStyles },
+        })
+      : children;
+
   if (portal) {
     return (
       <FloatingNode id={nodeId}>
         <FloatingPortal root={effectiveRoot}>
-          {isOpen && (
+          {shouldRender && (
             <FloatingFocusManager
               context={context}
               initialFocus={initialFocus}
               outsideElementsInert={outsideElementsInert}
               order={order}
               modal={modal}
             >
-              <>{children}</>
+              <>{content}</>
             </FloatingFocusManager>
           )}
         </FloatingPortal>
@@ -69,14 +151,15 @@ export const Popover = (props: PopoverProps) => {
 
   return (
     <FloatingNode id={nodeId}>
-      {isOpen && (
+      {shouldRender && (
         <FloatingFocusManager
           context={context}
           initialFocus={initialFocus}
+          outsideElementsInert={outsideElementsInert}
           order={order}
           modal={modal}
         >
-          <>{children}</>
+          <>{content}</>
         </FloatingFocusManager>
       )}
     </FloatingNode>