@base-ui/react 1.2.0 → 1.3.0

package/esm/labelable-provider/useAriaLabelledBy.js

@@ -0,0 +1,56 @@
+'use client';
+
+import * as React from 'react';
+import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
+import { useBaseUiId } from "../utils/useBaseUiId.js";
+
+/**
+ * @internal
+ */
+export function useAriaLabelledBy(explicitAriaLabelledBy, labelId, labelSourceRef, enableFallback = true, labelSourceId) {
+  const [fallbackAriaLabelledBy, setFallbackAriaLabelledBy] = React.useState();
+  const generatedLabelId = useBaseUiId(labelSourceId ? `${labelSourceId}-label` : undefined);
+  const ariaLabelledBy = explicitAriaLabelledBy ?? labelId ?? fallbackAriaLabelledBy;
+
+  // Fallback for <span> controls labelled by wrapping/sibling native <label>.
+  // Run after every commit so DOM association changes (e.g. label mount/unmount)
+  // are reflected even when props/state deps are unchanged.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useIsoLayoutEffect(() => {
+    const nextAriaLabelledBy = explicitAriaLabelledBy || labelId || !enableFallback ? undefined : getAriaLabelledBy(labelSourceRef.current, generatedLabelId);
+    if (fallbackAriaLabelledBy !== nextAriaLabelledBy) {
+      setFallbackAriaLabelledBy(nextAriaLabelledBy);
+    }
+  });
+  return ariaLabelledBy;
+}
+function getAriaLabelledBy(labelSource, generatedLabelId) {
+  const label = findAssociatedLabel(labelSource);
+  if (!label) {
+    return undefined;
+  }
+  if (!label.id && generatedLabelId) {
+    label.id = generatedLabelId;
+  }
+  return label.id || undefined;
+}
+function findAssociatedLabel(labelSource) {
+  if (!labelSource) {
+    return undefined;
+  }
+
+  // Fast path before the expensive `.labels` read.
+  const parent = labelSource.parentElement;
+  if (parent && parent.tagName === 'LABEL') {
+    return parent;
+  }
+  const controlId = labelSource.id;
+  if (controlId) {
+    const nextSibling = labelSource.nextElementSibling;
+    if (nextSibling && nextSibling.htmlFor === controlId) {
+      return nextSibling;
+    }
+  }
+  const labels = labelSource.labels;
+  return labels && labels[0];
+}

package/esm/labelable-provider/useLabel.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+export declare function useLabel(params?: UseLabelParameters): UseLabelReturnValue;
+export interface UseLabelParameters {
+  id?: string | undefined;
+  /**
+   * Control id used when no labelable context control id exists.
+   */
+  fallbackControlId?: string | null | undefined;
+  /**
+   * Whether the rendered element is a native `<label>`.
+   * @default false
+   */
+  native?: boolean | undefined;
+  /**
+   * Additional callback to sync the current label id with local component state/store.
+   */
+  setLabelId?: ((nextLabelId: string | undefined) => void) | undefined;
+  /**
+   * Custom focus handler for non-native labels.
+   * If omitted, focus behavior targets the resolved control id.
+   */
+  focusControl?: ((event: React.MouseEvent, controlId: string | null | undefined) => void) | undefined;
+}
+export type UseLabelReturnValue = React.HTMLAttributes<any> & React.LabelHTMLAttributes<any>;
+export declare function focusElementWithVisible(element: HTMLElement): void;

package/esm/labelable-provider/useLabel.js

@@ -0,0 +1,74 @@
+'use client';
+
+import { isHTMLElement } from '@floating-ui/utils/dom';
+import { ownerDocument } from '@base-ui/utils/owner';
+import { useStableCallback } from '@base-ui/utils/useStableCallback';
+import { getTarget } from "../floating-ui-react/utils.js";
+import { useRegisteredLabelId } from "../utils/useRegisteredLabelId.js";
+import { useLabelableContext } from "./LabelableContext.js";
+export function useLabel(params = {}) {
+  const {
+    id: idProp,
+    fallbackControlId,
+    native = false,
+    setLabelId: setLabelIdProp,
+    focusControl: focusControlProp
+  } = params;
+  const {
+    controlId: contextControlId,
+    setLabelId: setContextLabelId
+  } = useLabelableContext();
+  const syncLabelId = useStableCallback(nextLabelId => {
+    setContextLabelId(nextLabelId);
+    setLabelIdProp?.(nextLabelId);
+  });
+  const id = useRegisteredLabelId(idProp, syncLabelId);
+  const resolvedControlId = contextControlId ?? fallbackControlId;
+  function focusControl(event) {
+    if (focusControlProp) {
+      focusControlProp(event, resolvedControlId);
+      return;
+    }
+    if (!resolvedControlId) {
+      return;
+    }
+    const controlElement = ownerDocument(event.currentTarget).getElementById(resolvedControlId);
+    if (isHTMLElement(controlElement)) {
+      focusElementWithVisible(controlElement);
+    }
+  }
+  function handleInteraction(event) {
+    const target = getTarget(event.nativeEvent);
+    if (target?.closest('button,input,select,textarea')) {
+      return;
+    }
+
+    // Prevent text selection when double clicking label.
+    if (!event.defaultPrevented && event.detail > 1) {
+      event.preventDefault();
+    }
+    if (native) {
+      return;
+    }
+    focusControl(event);
+  }
+  return native ? {
+    id,
+    htmlFor: resolvedControlId ?? undefined,
+    onMouseDown: handleInteraction
+  } : {
+    id,
+    onClick: handleInteraction,
+    onPointerDown(event) {
+      event.preventDefault();
+    }
+  };
+}
+export function focusElementWithVisible(element) {
+  element.focus({
+    // Available from Chrome 144+ (January 2026).
+    // Safari and Firefox already support it.
+    // @ts-expect-error not available in types yet
+    focusVisible: true
+  });
+}

package/esm/labelable-provider/useLabelableId.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-export declare function useLabelableId(params?: useLabelableId.Parameters): string | undefined;
+export declare function useLabelableId(params?: UseLabelableIdParameters): string | undefined;
 export interface UseLabelableIdParameters {
   id?: string | undefined;
   /**
@@ -13,7 +13,4 @@ export interface UseLabelableIdParameters {
   controlRef?: React.RefObject<HTMLElement | null> | undefined;
 }
 export type UseLabelableIdReturnValue = string;
-export declare namespace useLabelableId {
-  type Parameters = UseLabelableIdParameters;
-  type ReturnValue = UseLabelableIdReturnValue;
-}
+export interface UseLabelableIdState {}

package/esm/menu/arrow/MenuArrow.d.ts

@@ -13,11 +13,20 @@ export interface MenuArrowState {
    * Whether the menu is currently open.
    */
   open: boolean;
+  /**
+   * The side of the anchor the component is placed on.
+   */
   side: Side;
+  /**
+   * The alignment of the component relative to the anchor.
+   */
   align: Align;
+  /**
+   * Whether the arrow cannot be centered on the anchor.
+   */
   uncentered: boolean;
 }
-export interface MenuArrowProps extends BaseUIComponentProps<'div', MenuArrow.State> {}
+export interface MenuArrowProps extends BaseUIComponentProps<'div', MenuArrowState> {}
 export declare namespace MenuArrow {
   type State = MenuArrowState;
   type Props = MenuArrowProps;

package/esm/menu/backdrop/MenuBackdrop.d.ts

@@ -13,9 +13,12 @@ export interface MenuBackdropState {
    * Whether the menu is currently open.
    */
   open: boolean;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
-export interface MenuBackdropProps extends BaseUIComponentProps<'div', MenuBackdrop.State> {}
+export interface MenuBackdropProps extends BaseUIComponentProps<'div', MenuBackdropState> {}
 export declare namespace MenuBackdrop {
   type State = MenuBackdropState;
   type Props = MenuBackdropProps;

package/esm/menu/checkbox-item/MenuCheckboxItem.d.ts

@@ -8,7 +8,7 @@ import type { MenuRoot } from "../root/MenuRoot.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuCheckboxItem: React.ForwardRefExoticComponent<Omit<MenuCheckboxItemProps, "ref"> & React.RefAttributes<HTMLElement>>;
-export type MenuCheckboxItemState = {
+export interface MenuCheckboxItemState {
   /**
    * Whether the checkbox item should ignore user interaction.
    */
@@ -21,8 +21,8 @@ export type MenuCheckboxItemState = {
    * Whether the checkbox item is currently ticked.
    */
   checked: boolean;
-};
-export interface MenuCheckboxItemProps extends NonNativeButtonProps, BaseUIComponentProps<'div', MenuCheckboxItem.State> {
+}
+export interface MenuCheckboxItemProps extends NonNativeButtonProps, BaseUIComponentProps<'div', MenuCheckboxItemState> {
   /**
    * Whether the checkbox item is currently ticked.
    *

package/esm/menu/checkbox-item-indicator/MenuCheckboxItemIndicator.d.ts

@@ -8,7 +8,7 @@ import { TransitionStatus } from "../../utils/useTransitionStatus.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuCheckboxItemIndicator: React.ForwardRefExoticComponent<Omit<MenuCheckboxItemIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
-export interface MenuCheckboxItemIndicatorProps extends BaseUIComponentProps<'span', MenuCheckboxItemIndicator.State> {
+export interface MenuCheckboxItemIndicatorProps extends BaseUIComponentProps<'span', MenuCheckboxItemIndicatorState> {
   /**
    * Whether to keep the HTML element in the DOM when the checkbox item is not checked.
    * @default false
@@ -24,7 +24,13 @@ export interface MenuCheckboxItemIndicatorState {
    * Whether the component should ignore user interaction.
    */
   disabled: boolean;
+  /**
+   * Whether the item is highlighted.
+   */
   highlighted: boolean;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
 export declare namespace MenuCheckboxItemIndicator {

package/esm/menu/group/MenuGroup.d.ts

@@ -7,7 +7,7 @@ import { BaseUIComponentProps } from "../../utils/types.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuGroup: React.ForwardRefExoticComponent<Omit<MenuGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface MenuGroupProps extends BaseUIComponentProps<'div', MenuGroup.State> {
+export interface MenuGroupProps extends BaseUIComponentProps<'div', MenuGroupState> {
   /**
    * The content of the component.
    */

package/esm/menu/group-label/MenuGroupLabel.d.ts

@@ -7,7 +7,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuGroupLabel: React.ForwardRefExoticComponent<Omit<MenuGroupLabelProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface MenuGroupLabelProps extends BaseUIComponentProps<'div', MenuGroupLabel.State> {}
+export interface MenuGroupLabelProps extends BaseUIComponentProps<'div', MenuGroupLabelState> {}
 export interface MenuGroupLabelState {}
 export declare namespace MenuGroupLabel {
   type Props = MenuGroupLabelProps;

package/esm/menu/index.d.ts

@@ -16,4 +16,5 @@ export type * from "./radio-item/MenuRadioItem.js";
 export type * from "./radio-item-indicator/MenuRadioItemIndicator.js";
 export type * from "./submenu-root/MenuSubmenuRoot.js";
 export type * from "./trigger/MenuTrigger.js";
-export type * from "./submenu-trigger/MenuSubmenuTrigger.js";
+export type * from "./submenu-trigger/MenuSubmenuTrigger.js";
+export type * from "./viewport/MenuViewport.js";

package/esm/menu/index.parts.d.ts

@@ -15,6 +15,7 @@ export { MenuRadioItemIndicator as RadioItemIndicator } from "./radio-item-indic
 export { MenuRoot as Root } from "./root/MenuRoot.js";
 export { MenuSubmenuRoot as SubmenuRoot } from "./submenu-root/MenuSubmenuRoot.js";
 export { MenuTrigger as Trigger } from "./trigger/MenuTrigger.js";
+export { MenuViewport as Viewport } from "./viewport/MenuViewport.js";
 export { Separator } from "../separator/Separator.js";
 export { MenuSubmenuTrigger as SubmenuTrigger } from "./submenu-trigger/MenuSubmenuTrigger.js";
 export { MenuHandle as Handle, createMenuHandle as createHandle } from "./store/MenuHandle.js";

package/esm/menu/index.parts.js

@@ -15,6 +15,7 @@ export { MenuRadioItemIndicator as RadioItemIndicator } from "./radio-item-indic
 export { MenuRoot as Root } from "./root/MenuRoot.js";
 export { MenuSubmenuRoot as SubmenuRoot } from "./submenu-root/MenuSubmenuRoot.js";
 export { MenuTrigger as Trigger } from "./trigger/MenuTrigger.js";
+export { MenuViewport as Viewport } from "./viewport/MenuViewport.js";
 export { Separator } from "../separator/Separator.js";
 export { MenuSubmenuTrigger as SubmenuTrigger } from "./submenu-trigger/MenuSubmenuTrigger.js";
 export { MenuHandle as Handle, createMenuHandle as createHandle } from "./store/MenuHandle.js";

package/esm/menu/item/MenuItem.d.ts

@@ -17,7 +17,7 @@ export interface MenuItemState {
    */
   highlighted: boolean;
 }
-export interface MenuItemProps extends NonNativeButtonProps, BaseUIComponentProps<'div', MenuItem.State> {
+export interface MenuItemProps extends NonNativeButtonProps, BaseUIComponentProps<'div', MenuItemState> {
   /**
    * The click handler for the menu item.
    */

package/esm/menu/item/useMenuItem.d.ts

@@ -4,7 +4,7 @@ import { MenuStore } from "../store/MenuStore.js";
 export declare const REGULAR_ITEM: {
   type: "regular-item";
 };
-export declare function useMenuItem(params: useMenuItem.Parameters): useMenuItem.ReturnValue;
+export declare function useMenuItem(params: UseMenuItemParameters): UseMenuItemReturnValue;
 export interface UseMenuItemParameters {
   /**
    * Whether to close the menu when the item is clicked.
@@ -32,7 +32,7 @@ export interface UseMenuItemParameters {
   /**
    * Additional data specific to the item type.
    */
-  itemMetadata: useMenuItem.Metadata;
+  itemMetadata: UseMenuItemMetadata;
   /**
    * The node id of the menu positioner.
    */
@@ -41,6 +41,11 @@ export interface UseMenuItemParameters {
    * The menu store.
    */
   store: MenuStore<any>;
+  /**
+   * Whether a typeahead session is in progress.
+   * @default store.context.typingRef
+   */
+  typingRef?: React.RefObject<boolean> | undefined;
 }
 export type UseMenuItemMetadata = typeof REGULAR_ITEM | {
   type: 'submenu-trigger';
@@ -58,8 +63,4 @@ export interface UseMenuItemReturnValue {
    */
   itemRef: React.RefCallback<HTMLElement> | null;
 }
-export declare namespace useMenuItem {
-  type Parameters = UseMenuItemParameters;
-  type Metadata = UseMenuItemMetadata;
-  type ReturnValue = UseMenuItemReturnValue;
-}
+export interface UseMenuItemState {}

package/esm/menu/item/useMenuItem.js

@@ -15,6 +15,7 @@ export function useMenuItem(params) {
     highlighted,
     id,
     store,
+    typingRef = store.context.typingRef,
     nativeButton,
     itemMetadata,
     nodeId
@@ -26,7 +27,8 @@ export function useMenuItem(params) {
   } = useButton({
     disabled,
     focusableWhenDisabled: true,
-    native: nativeButton
+    native: nativeButton,
+    composite: true
   });
   const commonProps = useMenuItemCommonProps({
     closeOnClick,
@@ -34,6 +36,7 @@ export function useMenuItem(params) {
     id,
     nodeId,
     store,
+    typingRef,
     itemRef,
     itemMetadata
   });
@@ -44,14 +47,9 @@ export function useMenuItem(params) {
           return;
         }
         itemMetadata.setActive();
-      },
-      onKeyUp(event) {
-        if (event.key === ' ' && store.context.typingRef.current) {
-          event.preventBaseUIHandler();
-        }
       }
     }, externalProps, getButtonProps);
-  }, [commonProps, getButtonProps, store, itemMetadata]);
+  }, [commonProps, getButtonProps, itemMetadata]);
   const mergedRef = useMergedRefs(itemRef, buttonRef);
   return React.useMemo(() => ({
     getItemProps,

package/esm/menu/item/useMenuItemCommonProps.d.ts

@@ -23,6 +23,10 @@ export interface UseMenuItemCommonPropsParameters {
    * The menu store.
    */
   store: MenuStore<any>;
+  /**
+   * Whether a typeahead session is in progress.
+   */
+  typingRef?: React.RefObject<boolean> | undefined;
   /**
    * Ref to the item element.
    */
@@ -35,9 +39,8 @@ export interface UseMenuItemCommonPropsParameters {
 }
 /**
  * Returns common props shared by all menu item types.
- * This hook extracts the shared logic for id, role, tabIndex, onMouseMove, onClick, and onMouseUp handlers.
+ * This hook extracts the shared logic for id, role, tabIndex, onKeyDown,
+ * onMouseMove, onClick, and onMouseUp handlers.
  */
 export declare function useMenuItemCommonProps(params: UseMenuItemCommonPropsParameters): HTMLProps;
-export declare namespace useMenuItemCommonProps {
-  type Parameters = UseMenuItemCommonPropsParameters;
-}
+export interface UseMenuItemCommonPropsState {}

package/esm/menu/item/useMenuItemCommonProps.js

@@ -1,11 +1,13 @@
 'use client';
 
 import * as React from 'react';
+import { isMac } from '@base-ui/utils/detectBrowser';
 import { REASONS } from "../../utils/reasons.js";
 import { useContextMenuRootContext } from "../../context-menu/root/ContextMenuRootContext.js";
 /**
  * Returns common props shared by all menu item types.
- * This hook extracts the shared logic for id, role, tabIndex, onMouseMove, onClick, and onMouseUp handlers.
+ * This hook extracts the shared logic for id, role, tabIndex, onKeyDown,
+ * onMouseMove, onClick, and onMouseUp handlers.
  */
 export function useMenuItemCommonProps(params) {
   const {
@@ -14,6 +16,7 @@ export function useMenuItemCommonProps(params) {
     id,
     nodeId,
     store,
+    typingRef,
     itemRef,
     itemMetadata
   } = params;
@@ -26,6 +29,11 @@ export function useMenuItemCommonProps(params) {
     id,
     role: 'menuitem',
     tabIndex: highlighted ? 0 : -1,
+    onKeyDown(event) {
+      if (event.key === ' ' && typingRef?.current) {
+        event.preventDefault();
+      }
+    },
     onMouseMove(event) {
       if (!nodeId) {
         return;
@@ -53,6 +61,12 @@ export function useMenuItemCommonProps(params) {
         if (isContextMenu && initialCursorPoint && Math.abs(event.clientX - initialCursorPoint.x) <= 1 && Math.abs(event.clientY - initialCursorPoint.y) <= 1) {
           return;
         }
+
+        // On non-macOS platforms, this mouseup belongs to the right-click gesture
+        // that opened the context menu, so it must not activate an item.
+        if (isContextMenu && !isMac && event.button === 2) {
+          return;
+        }
       }
       if (itemRef.current && store.context.allowMouseUpTriggerRef.current && (!isContextMenu || event.button === 2)) {
         // This fires whenever the user clicks on the trigger, moves the cursor, and releases it over the item.
@@ -62,5 +76,5 @@ export function useMenuItemCommonProps(params) {
         }
       }
     }
-  }), [closeOnClick, highlighted, id, menuEvents, nodeId, store, itemRef, contextMenuContext, isContextMenu, itemMetadata]);
+  }), [closeOnClick, highlighted, id, menuEvents, nodeId, store, typingRef, itemRef, contextMenuContext, isContextMenu, itemMetadata]);
 }

package/esm/menu/link-item/MenuLinkItem.d.ts

@@ -13,7 +13,7 @@ export interface MenuLinkItemState {
    */
   highlighted: boolean;
 }
-export interface MenuLinkItemProps extends BaseUIComponentProps<'a', MenuLinkItem.State> {
+export interface MenuLinkItemProps extends BaseUIComponentProps<'a', MenuLinkItemState> {
   /**
    * Overrides the text label to use when the item is matched during keyboard text navigation.
    */

package/esm/menu/link-item/MenuLinkItem.js

@@ -7,6 +7,8 @@ import { useBaseUiId } from "../../utils/useBaseUiId.js";
 import { useCompositeListItem } from "../../composite/list/useCompositeListItem.js";
 import { useMenuPositionerContext } from "../positioner/MenuPositionerContext.js";
 import { useMenuItemCommonProps } from "../item/useMenuItemCommonProps.js";
+import { useButton } from "../../use-button/index.js";
+import { mergeProps } from "../../merge-props/index.js";
 
 /**
  * A link in the menu that can be used to navigate to a different page or section.
@@ -35,21 +37,33 @@ export const MenuLinkItem = /*#__PURE__*/React.forwardRef(function MenuLinkItem(
   } = useMenuRootContext();
   const highlighted = store.useState('isActive', listItem.index);
   const itemProps = store.useState('itemProps');
+  const typingRef = store.context.typingRef;
+  const {
+    getButtonProps,
+    buttonRef
+  } = useButton({
+    native: false,
+    composite: true
+  });
   const commonProps = useMenuItemCommonProps({
     closeOnClick,
     highlighted,
     id,
     nodeId,
     store,
+    typingRef,
     itemRef: linkRef
   });
+  function getItemProps(externalProps) {
+    return mergeProps(commonProps, externalProps, getButtonProps);
+  }
   const state = React.useMemo(() => ({
     highlighted
   }), [highlighted]);
   return useRenderElement('a', componentProps, {
     state,
-    props: [itemProps, elementProps, commonProps],
-    ref: [linkRef, forwardedRef, listItem.ref]
+    props: [itemProps, elementProps, getItemProps],
+    ref: [linkRef, buttonRef, forwardedRef, listItem.ref]
   });
 });
 if (process.env.NODE_ENV !== "production") MenuLinkItem.displayName = "MenuLinkItem";

package/esm/menu/popup/MenuPopup.d.ts

@@ -10,7 +10,7 @@ import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuPopup: React.ForwardRefExoticComponent<Omit<MenuPopupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface MenuPopupProps extends BaseUIComponentProps<'div', MenuPopup.State> {
+export interface MenuPopupProps extends BaseUIComponentProps<'div', MenuPopupState> {
   children?: React.ReactNode;
   /**
    * @ignore
@@ -25,19 +25,34 @@ export interface MenuPopupProps extends BaseUIComponentProps<'div', MenuPopup.St
    * - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
    *   Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
    */
-  finalFocus?: (boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | HTMLElement | null | void)) | undefined;
+  finalFocus?: boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | HTMLElement | null | void) | undefined;
 }
-export type MenuPopupState = {
+export interface MenuPopupState {
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
+  /**
+   * The side of the anchor the component is placed on.
+   */
   side: Side;
+  /**
+   * The alignment of the component relative to the anchor.
+   */
   align: Align;
   /**
    * Whether the menu is currently open.
    */
   open: boolean;
+  /**
+   * Whether the component is nested.
+   */
   nested: boolean;
-  instant: 'dismiss' | 'click' | 'group' | undefined;
-};
+  /**
+   * Whether transitions should be skipped.
+   */
+  instant: 'dismiss' | 'click' | 'group' | 'trigger-change' | undefined;
+}
 export declare namespace MenuPopup {
   type Props = MenuPopupProps;
   type State = MenuPopupState;

package/esm/menu/popup/MenuPopup.js

@@ -86,9 +86,12 @@ export const MenuPopup = /*#__PURE__*/React.forwardRef(function MenuPopup(compon
     nested: parent.type === 'menu',
     instant: instantType
   };
+  const setPopupElement = React.useCallback(element => {
+    store.set('popupElement', element);
+  }, [store]);
   const element = useRenderElement('div', componentProps, {
     state,
-    ref: [forwardedRef, store.context.popupRef],
+    ref: [forwardedRef, store.context.popupRef, setPopupElement],
     stateAttributesMapping,
     props: [popupProps, {
       onKeyDown(event) {

package/esm/menu/popup/MenuPopupDataAttributes.d.ts

@@ -27,7 +27,7 @@ export declare enum MenuPopupDataAttributes {
   align = "data-align",
   /**
    * Present if animations should be instant.
-   * @type {'click' | 'dismiss' | 'group'}
+   * @type {'click' | 'dismiss' | 'group' | 'trigger-change'}
    */
   instant = "data-instant",
 }

package/esm/menu/popup/MenuPopupDataAttributes.js

@@ -28,7 +28,7 @@ export let MenuPopupDataAttributes = function (MenuPopupDataAttributes) {
   MenuPopupDataAttributes[MenuPopupDataAttributes["align"] = CommonPopupDataAttributes.align] = "align";
   /**
    * Present if animations should be instant.
-   * @type {'click' | 'dismiss' | 'group'}
+   * @type {'click' | 'dismiss' | 'group' | 'trigger-change'}
    */
   MenuPopupDataAttributes["instant"] = "data-instant";
   return MenuPopupDataAttributes;

package/esm/menu/portal/MenuPortal.d.ts

@@ -8,10 +8,8 @@ import { FloatingPortal } from "../../floating-ui-react/index.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuPortal: React.ForwardRefExoticComponent<Omit<MenuPortalProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare namespace MenuPortal {
-  interface State {}
-}
-export interface MenuPortalProps extends FloatingPortal.Props<MenuPortal.State> {
+export interface MenuPortalState {}
+export interface MenuPortalProps extends FloatingPortal.Props<MenuPortalState> {
   /**
    * Whether to keep the portal mounted in the DOM while the popup is hidden.
    * @default false
@@ -19,5 +17,6 @@ export interface MenuPortalProps extends FloatingPortal.Props<MenuPortal.State>
   keepMounted?: boolean | undefined;
 }
 export declare namespace MenuPortal {
+  type State = MenuPortalState;
   type Props = MenuPortalProps;
 }