@base-ui/react 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,152 @@
 # Versions
 
+## v1.3.0
+
+_Mar 12, 2026_
+
+### General Changes
+
+- Warn when a component function is rendered directly (#4077) by @atomiks
+- Reset `openMethod` after close transition (#4128) by @atomiks
+- Fire <kbd>Space</kbd> activation on `keydown` in composite widgets (#4053) by @atomiks
+- Skip CSS-hidden items during keyboard navigation in composite widgets (#4195) by @atomiks
+- Optimize hot paths in `useHover` hooks and `safePolygon` (#4199) by @atomiks
+- Snap `--anchor-width` and `--anchor-height` to device pixel grid (#4082) by @flaviendelangle
+- Fix outside press dismissal when a component is portaled into a shadow DOM (#4230) by @dmitri-gb
+- Fix nested hoverable popups (#4206) by @dmitri-gb
+- Apply `data-base-ui-inert` to highest-level node (#3955) by @atomiks
+- Fix portable types (#4058) by @cgatian
+
+### Accordion
+
+- Add generic `Value` typing (#4138) by @atomiks
+
+### Autocomplete
+
+- Respect a `null` `filter` prop (#4117) by @atomiks
+- Add `InputGroup` part (#3745) by @atomiks
+
+### Avatar
+
+- Remove fallback transition logic and prevent premature image display (#4110) by @atomiks
+
+### Button
+
+- Avoid checking `disabled` twice in `onKeyDown` and `onKeyUp` (#4132) by @flaviendelangle
+
+### Checkbox
+
+- Add automatic `aria-labelledby` support (#4142) by @atomiks
+
+### Combobox
+
+- Avoid applying field attributes to input when it is inside popup (#4154) by @atomiks
+- Preserve inline input on `Enter` when nothing is highlighted (#4235) by @atomiks
+- Fix ARIA attributes during SSR (#4179) by @atomiks
+- Fix wrapping in virtualized grid arrow-key navigation (#4164) by @atomiks
+- Add `InputGroup` part (#3745) by @atomiks
+- Add support for a visually hidden close button and improve modal focus trapping (#4084) by @atomiks
+- Add `Label` part (#4167) by @atomiks
+
+### Context Menu
+
+- Ignore `mouseup` on non-Mac platforms (#3944) by @atomiks
+
+### Drawer
+
+- **Breaking change:** `Drawer` is no longer marked as preview<br />
+  `Drawer` is now stable and should be imported as `{ Drawer } from '@base-ui/react/drawer'` (#4293) by @atomiks
+- Fix React 17 support (#4178) by @atomiks
+- Include border in frontmost height variable (#4202) by @atomiks
+- Improve touch selection (#4104) by @atomiks
+- Preserve cross-axis scrolling during touch gestures (#4187) by @atomiks
+- Prevent swipe dismissal when component is controlled (#4133) by @flaviendelangle
+- Add `SwipeArea` part (#4102) by @atomiks
+- Make `data-base-ui-swipe-ignore` explicit for touch interactions (#4295) by @atomiks
+- Disable inheritance for swipe CSS variables (#4099) by @atomiks
+
+### Field
+
+- Fix field validation when `Form` errors or `invalid` prop are present at same time (#4112) by @mj12albert
+
+### Menu
+
+- Prevent `pointerleave` from stealing focus from dialogs (#4125) by @atomiks
+- Optimize `pointer-events` for submenu hover interactions (#4231) by @atomiks
+- Fix `closeDelay` not being applied to `Menu.SubmenuTrigger` (#4134) by @flaviendelangle
+- Implement content transitions with `Viewport` (#4060) by @michaldudak
+
+### Meter
+
+- Fix label announcements in NVDA (#4200) by @mj12albert
+
+### Navigation Menu
+
+- Fix support for nested inline menus (#4198) by @atomiks
+- Fix close propagation in nested hover menus (#4285) by @atomiks
+- Close parent menus when nested link with `closeOnClick` is clicked (#4276) by @CiscoFran10
+- Fix duplicate `aria-orientation` (#4309) by @atomiks
+- Fix delayed trigger switches in Safari (#4310) by @atomiks
+
+### Number Field
+
+- Fix increment/decrement press `reason` values in `onValueCommitted` (#4259) by @jijiseong
+
+### Popover
+
+- Trap focus when `<Popover.Close>` is rendered inside and `modal` is `true`, and add support for a visually hidden close button (#4084) by @atomiks
+- Fix nested hoverable popups (#3798) by @flaviendelangle
+
+### Preview Card
+
+- Fix nested hoverable popups (#3798) by @flaviendelangle
+
+### Progress
+
+- Fix label announcements in NVDA (#4200) by @mj12albert
+
+### Radio Group
+
+- Add automatic `aria-labelledby` support (#4142) by @atomiks
+
+### Scroll Area
+
+- Fix focus trapping with a non-scrollable viewport (#4220) by @atomiks
+- Fix thumb size after remounting (#4107) by @atomiks
+
+### Select
+
+- Fix hidden input `id` fallback (#4135) by @atomiks
+- Fix `Value` placeholder not rendering with `Record` items (#4137) by @vcode-sh
+- Fire `onClick` during drag-to-select (#3969) by @obeattie
+- Fix `items` type definition for groups (#3884) by @aarongarciah
+- Fix `alignItemWithTrigger` fallback with browser zoom (#4292) by @atomiks
+- Add `Label` part (#4167) by @atomiks
+
+### Slider
+
+- Add `Label` part (#4167) by @atomiks
+- Stop committing validation on `touchend` (#4091) by @jijiseong
+
+### Switch
+
+- Add automatic `aria-labelledby` support (#4142) by @atomiks
+
+### Tabs
+
+- Re-render indicator position on tab resize (#4165) by @atomiks
+
+### Toast
+
+- Enable closing all toasts (#3979) by @chuganzy
+- Prevent duplicate `onClose` calls for ending toasts (#4280) by @chuganzy
+
+### Tooltip
+
+- Add `closeOnClick` prop (#4140) by @atomiks
+
+All contributors of this release in alphabetical order : @aarongarciah, @atomiks, @cgatian, @chuganzy, @CiscoFran10, @dmitri-gb, @flaviendelangle, @jijiseong, @michaldudak, @mj12albert, @obeattie, @vcode-sh
+
 ## v1.2.0
 
 _Feb 12, 2026_
@@ -937,7 +1084,7 @@ _Sep 3, 2025_
   ```diff
   -onOpenChange: (open, event, reason) => {
   +onOpenChange: (open, eventDetails) => {
-  -  if (reason === 'escape-key') {
+  - if (reason === 'escape-key') {
   +  if (eventDetails.reason === 'escape-key') {
        // ...
      }

package/accordion/header/AccordionHeader.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { BaseUIComponentProps } from "../../utils/types.js";
-import type { AccordionItem } from "../item/AccordionItem.js";
+import type { AccordionItemState } from "../item/AccordionItem.js";
 /**
  * A heading that labels the corresponding panel.
  * Renders an `<h3>` element.
@@ -8,7 +8,9 @@ import type { AccordionItem } from "../item/AccordionItem.js";
  * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
  */
 export declare const AccordionHeader: React.ForwardRefExoticComponent<Omit<AccordionHeaderProps, "ref"> & React.RefAttributes<HTMLHeadingElement>>;
-export interface AccordionHeaderProps extends BaseUIComponentProps<'h3', AccordionItem.State> {}
+export interface AccordionHeaderState extends AccordionItemState {}
+export interface AccordionHeaderProps extends BaseUIComponentProps<'h3', AccordionHeaderState> {}
 export declare namespace AccordionHeader {
+  type State = AccordionHeaderState;
   type Props = AccordionHeaderProps;
 }

package/accordion/item/AccordionItem.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { BaseUIComponentProps } from "../../utils/types.js";
-import { useCollapsibleRoot } from "../../collapsible/root/useCollapsibleRoot.js";
-import type { AccordionRoot } from "../root/AccordionRoot.js";
+import { type UseCollapsibleRootParameters } from "../../collapsible/root/useCollapsibleRoot.js";
+import type { AccordionRootState } from "../root/AccordionRoot.js";
 import { type BaseUIChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
 import { REASONS } from "../../utils/reasons.js";
 /**
@@ -11,11 +11,17 @@ import { REASONS } from "../../utils/reasons.js";
  * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
  */
 export declare const AccordionItem: React.ForwardRefExoticComponent<Omit<AccordionItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface AccordionItemState extends AccordionRoot.State {
+export interface AccordionItemState extends AccordionRootState {
+  /**
+   * The item index.
+   */
   index: number;
+  /**
+   * Whether the component is open.
+   */
   open: boolean;
 }
-export interface AccordionItemProps extends BaseUIComponentProps<'div', AccordionItem.State>, Partial<Pick<useCollapsibleRoot.Parameters, 'disabled'>> {
+export interface AccordionItemProps extends BaseUIComponentProps<'div', AccordionItemState>, Partial<Pick<UseCollapsibleRootParameters, 'disabled'>> {
   /**
    * A unique value that identifies this accordion item.
    * If no value is provided, a unique ID will be generated automatically.

package/accordion/item/AccordionItemContext.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
-import type { AccordionItem } from "./AccordionItem.js";
+import type { AccordionItemState } from "./AccordionItem.js";
 export interface AccordionItemContext {
   open: boolean;
-  state: AccordionItem.State;
+  state: AccordionItemState;
   setTriggerId: (id: string | undefined) => void;
   triggerId?: string | undefined;
 }

package/accordion/item/stateAttributesMapping.d.ts

@@ -1,3 +1,3 @@
 import type { StateAttributesMapping } from "../../utils/getStateAttributesProps.js";
-import type { AccordionItem } from "./AccordionItem.js";
-export declare const accordionStateAttributesMapping: StateAttributesMapping<AccordionItem.State>;
+import type { AccordionItemState } from "./AccordionItem.js";
+export declare const accordionStateAttributesMapping: StateAttributesMapping<AccordionItemState>;

package/accordion/panel/AccordionPanel.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { BaseUIComponentProps } from "../../utils/types.js";
 import type { AccordionRoot } from "../root/AccordionRoot.js";
-import type { AccordionItem } from "../item/AccordionItem.js";
+import type { AccordionItemState } from "../item/AccordionItem.js";
 import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
 /**
  * A collapsible panel with the accordion item contents.
@@ -10,10 +10,13 @@ import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
  * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
  */
 export declare const AccordionPanel: React.ForwardRefExoticComponent<Omit<AccordionPanelProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface AccordionPanelState extends AccordionItem.State {
+export interface AccordionPanelState extends AccordionItemState {
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
-export interface AccordionPanelProps extends BaseUIComponentProps<'div', AccordionPanel.State>, Pick<AccordionRoot.Props, 'hiddenUntilFound' | 'keepMounted'> {}
+export interface AccordionPanelProps extends BaseUIComponentProps<'div', AccordionPanelState>, Pick<AccordionRoot.Props, 'hiddenUntilFound' | 'keepMounted'> {}
 export declare namespace AccordionPanel {
   type State = AccordionPanelState;
   type Props = AccordionPanelProps;

package/accordion/root/AccordionRoot.d.ts

@@ -8,29 +8,37 @@ import { REASONS } from "../../utils/reasons.js";
  *
  * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
  */
-export declare const AccordionRoot: React.ForwardRefExoticComponent<Omit<AccordionRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export type AccordionValue = (any | null)[];
-export interface AccordionRootState {
-  value: AccordionValue;
+export declare const AccordionRoot: {
+  <Value = any>(props: AccordionRoot.Props<Value>): React.JSX.Element;
+};
+export type AccordionValue<Value = any> = Value[];
+export interface AccordionRootState<Value = any> {
+  /**
+   * The current value.
+   */
+  value: AccordionValue<Value>;
   /**
    * Whether the component should ignore user interaction.
    */
   disabled: boolean;
+  /**
+   * The component orientation.
+   */
   orientation: Orientation;
 }
-export interface AccordionRootProps extends BaseUIComponentProps<'div', AccordionRoot.State> {
+export interface AccordionRootProps<Value = any> extends BaseUIComponentProps<'div', AccordionRoot.State<Value>> {
   /**
    * The controlled value of the item(s) that should be expanded.
    *
    * To render an uncontrolled accordion, use the `defaultValue` prop instead.
    */
-  value?: AccordionValue | undefined;
+  value?: AccordionValue<Value> | undefined;
   /**
    * The uncontrolled value of the item(s) that should be initially expanded.
    *
    * To render a controlled accordion, use the `value` prop instead.
    */
-  defaultValue?: AccordionValue | undefined;
+  defaultValue?: AccordionValue<Value> | undefined;
   /**
    * Whether the component should ignore user interaction.
    * @default false
@@ -60,7 +68,7 @@ export interface AccordionRootProps extends BaseUIComponentProps<'div', Accordio
    * Event handler called when an accordion item is expanded or collapsed.
    * Provides the new value as an argument.
    */
-  onValueChange?: ((value: AccordionValue, eventDetails: AccordionRootChangeEventDetails) => void) | undefined;
+  onValueChange?: ((value: AccordionValue<Value>, eventDetails: AccordionRootChangeEventDetails) => void) | undefined;
   /**
    * Whether multiple items can be open at the same time.
    * @default false
@@ -76,8 +84,9 @@ export interface AccordionRootProps extends BaseUIComponentProps<'div', Accordio
 export type AccordionRootChangeEventReason = typeof REASONS.triggerPress | typeof REASONS.none;
 export type AccordionRootChangeEventDetails = BaseUIChangeEventDetails<AccordionRoot.ChangeEventReason>;
 export declare namespace AccordionRoot {
-  type State = AccordionRootState;
-  type Props = AccordionRootProps;
+  type Value<TValue = any> = AccordionValue<TValue>;
+  type State<TValue = any> = AccordionRootState<TValue>;
+  type Props<TValue = any> = AccordionRootProps<TValue>;
   type ChangeEventReason = AccordionRootChangeEventReason;
   type ChangeEventDetails = AccordionRootChangeEventDetails;
 }

package/accordion/root/AccordionRootContext.d.ts

@@ -1,18 +1,18 @@
 import * as React from 'react';
 import type { Orientation } from "../../utils/types.js";
 import type { TextDirection } from "../../direction-provider/index.js";
-import type { AccordionRoot, AccordionValue } from "./AccordionRoot.js";
-export interface AccordionRootContext {
+import type { AccordionRoot } from "./AccordionRoot.js";
+export interface AccordionRootContext<Value = any> {
   accordionItemRefs: React.RefObject<(HTMLElement | null)[]>;
   direction: TextDirection;
   disabled: boolean;
-  handleValueChange: (newValue: number | string, nextOpen: boolean) => void;
+  handleValueChange: (newValue: AccordionRoot.Value<Value>[number], nextOpen: boolean) => void;
   hiddenUntilFound: boolean;
   keepMounted: boolean;
   loopFocus: boolean;
   orientation: Orientation;
-  state: AccordionRoot.State;
-  value: AccordionValue;
+  state: AccordionRoot.State<Value>;
+  value: AccordionRoot.Value<Value>;
 }
-export declare const AccordionRootContext: React.Context<AccordionRootContext | undefined>;
-export declare function useAccordionRootContext(): AccordionRootContext;
+export declare const AccordionRootContext: React.Context<AccordionRootContext<any> | undefined>;
+export declare function useAccordionRootContext<Value = any>(): AccordionRootContext<Value>;

package/accordion/trigger/AccordionTrigger.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { BaseUIComponentProps, NativeButtonProps } from "../../utils/types.js";
-import type { AccordionItem } from "../item/AccordionItem.js";
+import type { AccordionItemState } from "../item/AccordionItem.js";
 /**
  * A button that opens and closes the corresponding panel.
  * Renders a `<button>` element.
@@ -8,7 +8,9 @@ import type { AccordionItem } from "../item/AccordionItem.js";
  * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
  */
 export declare const AccordionTrigger: React.ForwardRefExoticComponent<Omit<AccordionTriggerProps, "ref"> & React.RefAttributes<HTMLElement>>;
-export interface AccordionTriggerProps extends NativeButtonProps, BaseUIComponentProps<'button', AccordionItem.State> {}
+export interface AccordionTriggerState extends AccordionItemState {}
+export interface AccordionTriggerProps extends NativeButtonProps, BaseUIComponentProps<'button', AccordionTriggerState> {}
 export declare namespace AccordionTrigger {
+  type State = AccordionTriggerState;
   type Props = AccordionTriggerProps;
 }

package/accordion/trigger/AccordionTrigger.js

@@ -63,7 +63,8 @@ const AccordionTrigger = exports.AccordionTrigger = /*#__PURE__*/React.forwardRe
   } = (0, _useButton.useButton)({
     disabled,
     focusableWhenDisabled: true,
-    native: nativeButton
+    native: nativeButton,
+    composite: true
   });
   const {
     accordionItemRefs,
@@ -90,6 +91,7 @@ const AccordionTrigger = exports.AccordionTrigger = /*#__PURE__*/React.forwardRe
     'aria-controls': open ? panelId : undefined,
     'aria-expanded': open,
     id,
+    tabIndex: 0,
     onClick: handleTrigger,
     onKeyDown(event) {
       if (!SUPPORTED_KEYS.has(event.key)) {

package/alert-dialog/root/AlertDialogRoot.d.ts

@@ -9,6 +9,7 @@ import type { DialogRoot } from "../../dialog/root/DialogRoot.js";
  * Documentation: [Base UI Alert Dialog](https://base-ui.com/react/components/alert-dialog)
  */
 export declare function AlertDialogRoot<Payload>(props: AlertDialogRoot.Props<Payload>): import("react/jsx-runtime").JSX.Element;
+export interface AlertDialogRootState {}
 export interface AlertDialogRootProps<Payload = unknown> extends Omit<DialogRoot.Props<Payload>, 'modal' | 'disablePointerDismissal' | 'onOpenChange' | 'actionsRef' | 'handle'> {
   /**
    * Event handler called when the dialog is opened or closed.
@@ -35,6 +36,7 @@ export type AlertDialogRootChangeEventDetails = BaseUIChangeEventDetails<AlertDi
   preventUnmountOnClose(): void;
 };
 export declare namespace AlertDialogRoot {
+  type State = AlertDialogRootState;
   type Props<Payload = unknown> = AlertDialogRootProps<Payload>;
   type Actions = AlertDialogRootActions;
   type ChangeEventReason = AlertDialogRootChangeEventReason;

package/autocomplete/index.d.ts

@@ -3,6 +3,7 @@ export type * from "./root/AutocompleteRoot.js";
 export type * from "./value/AutocompleteValue.js";
 export type { ComboboxTriggerProps as AutocompleteTriggerProps, ComboboxTriggerState as AutocompleteTriggerState } from "../combobox/trigger/ComboboxTrigger.js";
 export type { ComboboxInputProps as AutocompleteInputProps, ComboboxInputState as AutocompleteInputState } from "../combobox/input/ComboboxInput.js";
+export type { ComboboxInputGroupProps as AutocompleteInputGroupProps, ComboboxInputGroupState as AutocompleteInputGroupState } from "../combobox/input-group/ComboboxInputGroup.js";
 export type { ComboboxPopupProps as AutocompletePopupProps, ComboboxPopupState as AutocompletePopupState } from "../combobox/popup/ComboboxPopup.js";
 export type { ComboboxPositionerProps as AutocompletePositionerProps, ComboboxPositionerState as AutocompletePositionerState } from "../combobox/positioner/ComboboxPositioner.js";
 export type { ComboboxListProps as AutocompleteListProps, ComboboxListState as AutocompleteListState } from "../combobox/list/ComboboxList.js";

package/autocomplete/index.parts.d.ts

@@ -2,6 +2,7 @@ export { AutocompleteRoot as Root } from "./root/AutocompleteRoot.js";
 export { AutocompleteValue as Value } from "./value/AutocompleteValue.js";
 export { ComboboxTrigger as Trigger } from "../combobox/trigger/ComboboxTrigger.js";
 export { ComboboxInput as Input } from "../combobox/input/ComboboxInput.js";
+export { ComboboxInputGroup as InputGroup } from "../combobox/input-group/ComboboxInputGroup.js";
 export { ComboboxIcon as Icon } from "../combobox/icon/ComboboxIcon.js";
 export { ComboboxClear as Clear } from "../combobox/clear/ComboboxClear.js";
 export { ComboboxList as List } from "../combobox/list/ComboboxList.js";

package/autocomplete/index.parts.js

@@ -57,6 +57,12 @@ Object.defineProperty(exports, "Input", {
     return _ComboboxInput.ComboboxInput;
   }
 });
+Object.defineProperty(exports, "InputGroup", {
+  enumerable: true,
+  get: function () {
+    return _ComboboxInputGroup.ComboboxInputGroup;
+  }
+});
 Object.defineProperty(exports, "Item", {
   enumerable: true,
   get: function () {
@@ -139,6 +145,7 @@ var _AutocompleteRoot = require("./root/AutocompleteRoot");
 var _AutocompleteValue = require("./value/AutocompleteValue");
 var _ComboboxTrigger = require("../combobox/trigger/ComboboxTrigger");
 var _ComboboxInput = require("../combobox/input/ComboboxInput");
+var _ComboboxInputGroup = require("../combobox/input-group/ComboboxInputGroup");
 var _ComboboxIcon = require("../combobox/icon/ComboboxIcon");
 var _ComboboxClear = require("../combobox/clear/ComboboxClear");
 var _ComboboxList = require("../combobox/list/ComboboxList");

package/autocomplete/root/AutocompleteRoot.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { AriaCombobox } from "../../combobox/root/AriaCombobox.js";
+import { AriaCombobox, type AriaComboboxState } from "../../combobox/root/AriaCombobox.js";
 /**
  * Groups all parts of the autocomplete.
  * Doesn't render its own HTML element.
@@ -22,7 +22,7 @@ export declare function AutocompleteRoot<ItemValue>(props: Omit<AutocompleteRoot
    */
   items?: readonly ItemValue[] | undefined;
 }): React.JSX.Element;
-export type AutocompleteRootState = AriaCombobox.State;
+export interface AutocompleteRootState extends AriaComboboxState {}
 export interface AutocompleteRootActions {
   unmount: () => void;
 }
@@ -39,14 +39,14 @@ export interface AutocompleteRootProps<ItemValue> extends Omit<AriaCombobox.Prop
    * - `none`: items are static (not filtered), and the input value will not change based on the active item.
    * @default 'list'
    */
-  mode?: ('list' | 'both' | 'inline' | 'none') | undefined;
+  mode?: 'list' | 'both' | 'inline' | 'none' | undefined;
   /**
    * Whether the first matching item is highlighted automatically.
    * - `true`: highlight after the user types and keep the highlight while the query changes.
    * - `'always'`: always highlight the first item.
    * @default false
    */
-  autoHighlight?: (boolean | 'always') | undefined;
+  autoHighlight?: boolean | 'always' | undefined;
   /**
    * Whether the highlighted item should be preserved when the pointer leaves the list.
    * @default false

package/autocomplete/root/AutocompleteRoot.js

@@ -62,7 +62,7 @@ function AutocompleteRoot(props) {
   });
   const collator = (0, _useFilter.useCoreFilter)();
   const baseFilter = React.useMemo(() => {
-    if (other.filter) {
+    if (other.filter !== undefined) {
       return other.filter;
     }
     return collator.contains;
@@ -74,6 +74,9 @@ function AutocompleteRoot(props) {
     if (mode !== 'both') {
       return staticItems ? null : baseFilter;
     }
+    if (baseFilter === null) {
+      return null;
+    }
     return (item, _query, toString) => {
       return baseFilter(item, resolvedQuery, toString);
     };

package/avatar/fallback/AvatarFallback.d.ts

@@ -1,7 +1,6 @@
 import * as React from 'react';
 import { BaseUIComponentProps } from "../../utils/types.js";
-import type { AvatarRoot } from "../root/AvatarRoot.js";
-import { type TransitionStatus } from "../../utils/useTransitionStatus.js";
+import type { AvatarRootState } from "../root/AvatarRoot.js";
 /**
  * Rendered when the image fails to load or when no image is provided.
  * Renders a `<span>` element.
@@ -9,10 +8,8 @@ import { type TransitionStatus } from "../../utils/useTransitionStatus.js";
  * Documentation: [Base UI Avatar](https://base-ui.com/react/components/avatar)
  */
 export declare const AvatarFallback: React.ForwardRefExoticComponent<Omit<AvatarFallbackProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
-export interface AvatarFallbackState extends AvatarRoot.State {
-  transitionStatus: TransitionStatus;
-}
-export interface AvatarFallbackProps extends BaseUIComponentProps<'span', AvatarFallback.State> {
+export interface AvatarFallbackState extends AvatarRootState {}
+export interface AvatarFallbackProps extends BaseUIComponentProps<'span', AvatarFallbackState> {
   /**
    * How long to wait before showing the fallback. Specified in milliseconds.
    */

package/avatar/fallback/AvatarFallback.js

@@ -11,14 +11,6 @@ var _useTimeout = require("@base-ui/utils/useTimeout");
 var _useRenderElement = require("../../utils/useRenderElement");
 var _AvatarRootContext = require("../root/AvatarRootContext");
 var _stateAttributesMapping = require("../root/stateAttributesMapping");
-var _useOpenChangeComplete = require("../../utils/useOpenChangeComplete");
-var _stateAttributesMapping2 = require("../../utils/stateAttributesMapping");
-var _useTransitionStatus = require("../../utils/useTransitionStatus");
-const stateAttributesMapping = {
-  ..._stateAttributesMapping.avatarStateAttributesMapping,
-  ..._stateAttributesMapping2.transitionStatusMapping
-};
-
 /**
  * Rendered when the image fails to load or when no image is provided.
  * Renders a `<span>` element.
@@ -37,13 +29,6 @@ const AvatarFallback = exports.AvatarFallback = /*#__PURE__*/React.forwardRef(fu
   } = (0, _AvatarRootContext.useAvatarRootContext)();
   const [delayPassed, setDelayPassed] = React.useState(delay === undefined);
   const timeout = (0, _useTimeout.useTimeout)();
-  const visible = imageLoadingStatus !== 'loaded' && delayPassed;
-  const {
-    mounted,
-    transitionStatus,
-    setMounted
-  } = (0, _useTransitionStatus.useTransitionStatus)(visible);
-  const fallbackRef = React.useRef(null);
   React.useEffect(() => {
     if (delay !== undefined) {
       timeout.start(delay, () => setDelayPassed(true));
@@ -51,28 +36,15 @@ const AvatarFallback = exports.AvatarFallback = /*#__PURE__*/React.forwardRef(fu
     return timeout.clear;
   }, [timeout, delay]);
   const state = {
-    imageLoadingStatus,
-    transitionStatus
+    imageLoadingStatus
   };
-  (0, _useOpenChangeComplete.useOpenChangeComplete)({
-    open: visible,
-    ref: fallbackRef,
-    onComplete() {
-      if (!visible) {
-        setMounted(false);
-      }
-    }
-  });
   const element = (0, _useRenderElement.useRenderElement)('span', componentProps, {
     state,
-    ref: [forwardedRef, fallbackRef],
+    ref: forwardedRef,
     props: elementProps,
-    stateAttributesMapping,
-    enabled: mounted
+    stateAttributesMapping: _stateAttributesMapping.avatarStateAttributesMapping,
+    enabled: imageLoadingStatus !== 'loaded' && delayPassed
   });
-  if (!mounted) {
-    return null;
-  }
   return element;
 });
 if (process.env.NODE_ENV !== "production") AvatarFallback.displayName = "AvatarFallback";

package/avatar/image/AvatarImage.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { BaseUIComponentProps } from "../../utils/types.js";
-import type { AvatarRoot } from "../root/AvatarRoot.js";
+import type { AvatarRootState } from "../root/AvatarRoot.js";
 import { type TransitionStatus } from "../../utils/useTransitionStatus.js";
 import { ImageLoadingStatus } from "./useImageLoadingStatus.js";
 /**
@@ -10,10 +10,13 @@ import { ImageLoadingStatus } from "./useImageLoadingStatus.js";
  * Documentation: [Base UI Avatar](https://base-ui.com/react/components/avatar)
  */
 export declare const AvatarImage: React.ForwardRefExoticComponent<Omit<AvatarImageProps, "ref"> & React.RefAttributes<HTMLImageElement>>;
-export interface AvatarImageState extends AvatarRoot.State {
+export interface AvatarImageState extends AvatarRootState {
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
-export interface AvatarImageProps extends BaseUIComponentProps<'img', AvatarImage.State> {
+export interface AvatarImageProps extends BaseUIComponentProps<'img', AvatarImageState> {
   /**
    * Callback fired when the loading status changes.
    */

package/avatar/image/AvatarImage.js

@@ -41,7 +41,7 @@ const AvatarImage = exports.AvatarImage = /*#__PURE__*/React.forwardRef(function
     referrerPolicy,
     crossOrigin
   });
-  const isVisible = imageLoadingStatus === 'loading' || imageLoadingStatus === 'loaded';
+  const isVisible = imageLoadingStatus === 'loaded';
   const {
     mounted,
     transitionStatus,
@@ -57,10 +57,9 @@ const AvatarImage = exports.AvatarImage = /*#__PURE__*/React.forwardRef(function
       handleLoadingStatusChange(imageLoadingStatus);
     }
   }, [imageLoadingStatus, handleLoadingStatusChange]);
-  const resolvedTransitionStatus = imageLoadingStatus === 'loading' ? 'starting' : transitionStatus;
   const state = {
     imageLoadingStatus,
-    transitionStatus: resolvedTransitionStatus
+    transitionStatus
   };
   (0, _useOpenChangeComplete.useOpenChangeComplete)({
     open: isVisible,

package/avatar/image/AvatarImageDataAttributes.d.ts

@@ -0,0 +1,10 @@
+export declare enum AvatarImageDataAttributes {
+  /**
+   * Present when the image is animating in.
+   */
+  startingStyle = "data-starting-style",
+  /**
+   * Present when the image is animating out.
+   */
+  endingStyle = "data-ending-style",
+}