@base-ui/react 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,178 @@
 # Versions
 
+## v1.2.0
+
+_Feb 12, 2026_
+
+### General changes
+
+- Do not memoize `state` when not needed (#3812) by @flaviendelangle
+- Support lazy element in `render` prop (#3856) by @oliviertassinari
+- Replace Firefox deprecated mozInputSource check for virtual click detection (#3942) by @CiscoFran10
+- Use `WeakRef` for previously focused elements (#3916) by @atomiks
+- Fix page scroll jump when input has focus on unmount in Safari (#3925) by @atomiks
+- Fix flash at origin before positioning completes in Preact (#3975) by @OliverSpeir
+- Reduce style recalculation with classic scrollbars (#3854) by @mdm317
+- Fix event handling in useEnhancedClickHandler (#3981) by @sai6855
+
+### Autocomplete
+
+- Fix filter method's `useMemo` dependency (#3862) by @ZeeshanTamboli
+- Fix Autocomplete not using its internal filter method when `mode` is `list` (#3936) by @ZeeshanTamboli
+- Remove unnecessary double stringification of item in filtering logic (#3945) by @ZeeshanTamboli
+- Add `useFilteredItems` hook (#3732) by @guisehn
+- Fix popup closing on iOS VoiceOver (#3859) by @atomiks
+- Remove `aria-readonly` prop from `Clear` and `Popup` components when `readOnly` (#3907) by @markocupic024
+
+### Avatar
+
+- Add transition attributes (#3939) by @atomiks
+
+### Button
+
+- Capture component stack for `nativeButton` error message (#3861) by @atomiks
+
+### Checkbox
+
+- Cleanup disabled state tracking (#3913) by @atomiks
+- Preserve modifier key properties in the change event (#3935) by @mj12albert
+- Allow exit animations on `<Checkbox.Indicator>` when `keepMounted={false}` (#3939) by @atomiks
+
+### Combobox
+
+- Fix the type of the ref of the `Icon` part (#3796) by @flaviendelangle
+- Avoid clearing selected value if item is not present in items array (#3824) by @atomiks
+- Fix highlight change reason in `ChipRemove` (#3980) by @sai6855
+- Keep highlight on last deselect (#3923) by @atomiks
+- Fix inline filtering after selection in single mode (#3978) by @atomiks
+- Clear highlight on inline blur when inline (#3973) by @atomiks
+- Prevent opening popup on autofill change (#3924) by @atomiks
+- Distinguish `input-press` from `trigger-press` in `onOpenChange` reason (#4015) by @jijiseong
+- Fix async items while popup is open (#4034) by @atomiks
+- Prevent `Chip` from receiving focus when `disabled` (#4044) by @jijiseong
+- Add `useFilteredItems` hook (#3732) by @guisehn
+- Fix popup closing on iOS VoiceOver (#3859) by @atomiks
+- Remove `aria-readonly` prop from `Clear` and `Popup` components when `readOnly` (#3907) by @markocupic024
+- Fix `onClick` `Item` type (#3964) by @atomiks
+- Use reactive `domReferenceElement` subscriptions (#4017) by @atomiks
+- Add `autoComplete` prop for explicit browser autofill support (#4005) by @mattrothenberg
+- Fix inconsistent isItemEqualToValue argument order (#4056) by @atomiks
+
+### Context Menu
+
+- Fix `disabled` prop not working (#3806) by @arturbien
+- Fix explicit `collisionAvoidance` with `side: 'flip'` not working (#3877) by @obeattie
+
+### Drawer
+
+- Create new Drawer / Sheet component (#3680) by @atomiks
+
+### Field
+
+- Prevent re-renders when `Field.Control` is uncontrolled (#3820) by @atomiks
+- Fix autofocus in SSR environments (#3871) by @mj12albert
+- Fix max update depth loop when using `<React.Activity>` (#3931) by @atomiks
+- Add transition attributes (#3939) by @atomiks
+
+### Input
+
+- Fix autofocus in SSR environments (#3871) by @mj12albert
+- Update ref type to `HTMLElement` (#3866) by @mj12albert
+
+### Menu
+
+- Fix `onClick` `Item` type (#3964) by @atomiks
+- Fix submenu stuck glitch (#3783) by @atomiks
+- Fix race conditions (#3821) by @atomiks
+- Add `<Menu.LinkItem>` part (#3400) by @mj12albert
+
+### Navigation Menu
+
+- Fix forwarded ref types (#3775) by @CrawlerCode
+- Add `keepMounted` prop to `Content` part (#3794) by @atomiks
+
+### Number Field
+
+- Fix click handlers on ScrubArea (#3827) by @mj12albert
+- Remove `event.isTrusted` (#3920) by @atomiks
+- Stop repeat change at bounds (#3915) by @atomiks
+- Add `allowOutOfRange` prop (#3919) by @atomiks
+- Fix pen pointer handling (#3917) by @atomiks
+- Fix missing field state data attributes (#3909) by @mj12albert
+
+### Popover
+
+- Fix missing `aria-owns` element (#3959) by @atomiks
+- Use reactive `domReferenceElement` subscriptions (#4017) by @atomiks
+- Fix broken scale transition with detached triggers (#3810) by @michaldudak
+
+### Preview Card
+
+- Fix broken scale transition with detached triggers (#3810) by @michaldudak
+
+### Progress
+
+- De-duplicate `formatValue` function (#3805) by @sai6855
+
+### Radio Group
+
+- Preserve modifier key properties in the change event (#3935) by @mj12albert
+- Allow exit animations on `<Radio.Indicator>` when `keepMounted={false}` (#3939) by @atomiks
+- Rely on individual radio hidden inputs (#3826) by @atomiks
+- Add generic `Value` typing to `Radio` (#4033) by @atomiks
+
+### Scroll Area
+
+- Add `data-scrolling` state attribute to `Root` and `Viewport` parts (#3823) by @arturbien
+- Fix overflow edge rounding (#3888) by @atomiks
+
+### Select
+
+- Add `finalFocus` prop (#3785) by @markocupic024
+- Fix `alignItemWithTrigger` transform with CSS animations (#3831) by @atomiks
+- Fix `highlightItemOnHover` not being respected (#3868) by @sarthakmalik0810
+- Reset typeahead on external blur (#2618) by @antonfrolovsky
+- Fix scroll height loop (#3795) by @atomiks
+- Add `autoComplete` prop for explicit browser autofill support (#4005) by @mattrothenberg
+- Fix inconsistent isItemEqualToValue argument order (#4056) by @atomiks
+
+### Slider
+
+- Fix missing field state data attributes (#3909) by @mj12albert
+- Fix change event cloning (#3960) by @atomiks
+
+### Switch
+
+- Preserve modifier key properties in the change event (#3935) by @mj12albert
+
+### Tabs
+
+- Add transition attributes to `<Tabs.Panel>` part (#3880) by @atomiks
+
+### Toast
+
+- Make `useToastManager` and `createToastManager` generic functions (#3882) by @solastley
+- Prevent dismissed promise toast from reopening on updates (#4040) by @atomiks
+- Introduce a store (#3464) by @flaviendelangle
+
+### Toggle
+
+- Improve type safety and inference (#3173) by @michaelhazan
+
+### Toggle Group
+
+- Type value as string to match Toggle (#3770) by @markocupic024
+- Enable `Home`/`End` key navigation (#3971) by @jijiseong
+- Improve type safety and inference (#3173) by @michaelhazan
+
+### Tooltip
+
+- Prevent opening when focusing a disabled Trigger (#3902) by @michaldudak
+- Fix broken scale transition with detached triggers (#3810) by @michaldudak
+- Fix disabled prop on Triggers (#4049) by @michaldudak
+
+All contributors of this release in alphabetical order : @antonfrolovsky, @arturbien, @atomiks, @CiscoFran10, @CrawlerCode, @flaviendelangle, @guisehn, @jijiseong, @LukasTy, @markocupic024, @mattrothenberg, @mdm317, @michaelhazan, @michaldudak, @mj12albert, @obeattie, @OliverSpeir, @oliviertassinari, @sai6855, @sarthakmalik0810, @solastley, @ZeeshanTamboli
+
 ## v1.1.0
 
 _Jan 15, 2026_

package/accordion/item/AccordionItem.d.ts

@@ -33,7 +33,7 @@ export interface AccordionItemProps extends BaseUIComponentProps<'div', Accordio
   /**
    * Event handler called when the panel is opened or closed.
    */
-  onOpenChange?: (open: boolean, eventDetails: AccordionItem.ChangeEventDetails) => void;
+  onOpenChange?: ((open: boolean, eventDetails: AccordionItem.ChangeEventDetails) => void) | undefined;
 }
 export type AccordionItemChangeEventReason = typeof REASONS.triggerPress | typeof REASONS.none;
 export type AccordionItemChangeEventDetails = BaseUIChangeEventDetails<AccordionItem.ChangeEventReason>;

package/accordion/item/AccordionItemContext.d.ts

@@ -4,7 +4,7 @@ export interface AccordionItemContext {
   open: boolean;
   state: AccordionItem.State;
   setTriggerId: (id: string | undefined) => void;
-  triggerId?: string;
+  triggerId?: string | undefined;
 }
 export declare const AccordionItemContext: React.Context<AccordionItemContext | undefined>;
 export declare function useAccordionItemContext(): AccordionItemContext;

package/accordion/root/AccordionRoot.d.ts

@@ -24,18 +24,18 @@ export interface AccordionRootProps extends BaseUIComponentProps<'div', Accordio
    *
    * To render an uncontrolled accordion, use the `defaultValue` prop instead.
    */
-  value?: AccordionValue;
+  value?: AccordionValue | 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;
+  defaultValue?: AccordionValue | undefined;
   /**
    * Whether the component should ignore user interaction.
    * @default false
    */
-  disabled?: boolean;
+  disabled?: boolean | undefined;
   /**
    * Allows the browser’s built-in page search to find and expand the panel contents.
    *
@@ -43,35 +43,35 @@ export interface AccordionRootProps extends BaseUIComponentProps<'div', Accordio
    * to hide the element without removing it from the DOM.
    * @default false
    */
-  hiddenUntilFound?: boolean;
+  hiddenUntilFound?: boolean | undefined;
   /**
    * Whether to keep the element in the DOM while the panel is closed.
    * This prop is ignored when `hiddenUntilFound` is used.
    * @default false
    */
-  keepMounted?: boolean;
+  keepMounted?: boolean | undefined;
   /**
    * Whether to loop keyboard focus back to the first item
    * when the end of the list is reached while using the arrow keys.
    * @default true
    */
-  loopFocus?: boolean;
+  loopFocus?: boolean | undefined;
   /**
    * Event handler called when an accordion item is expanded or collapsed.
    * Provides the new value as an argument.
    */
-  onValueChange?: (value: AccordionValue, eventDetails: AccordionRootChangeEventDetails) => void;
+  onValueChange?: ((value: AccordionValue, eventDetails: AccordionRootChangeEventDetails) => void) | undefined;
   /**
    * Whether multiple items can be open at the same time.
    * @default false
    */
-  multiple?: boolean;
+  multiple?: boolean | undefined;
   /**
    * The visual orientation of the accordion.
    * Controls whether roving focus uses left/right or up/down arrow keys.
    * @default 'vertical'
    */
-  orientation?: Orientation;
+  orientation?: Orientation | undefined;
 }
 export type AccordionRootChangeEventReason = typeof REASONS.triggerPress | typeof REASONS.none;
 export type AccordionRootChangeEventDetails = BaseUIChangeEventDetails<AccordionRoot.ChangeEventReason>;

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

@@ -13,7 +13,7 @@ export interface AlertDialogRootProps<Payload = unknown> extends Omit<DialogRoot
   /**
    * Event handler called when the dialog is opened or closed.
    */
-  onOpenChange?: (open: boolean, eventDetails: AlertDialogRoot.ChangeEventDetails) => void;
+  onOpenChange?: ((open: boolean, eventDetails: AlertDialogRoot.ChangeEventDetails) => void) | undefined;
   /**
    * A ref to imperative actions.
    * - `unmount`: When specified, the dialog will not be unmounted when closed.
@@ -21,13 +21,13 @@ export interface AlertDialogRootProps<Payload = unknown> extends Omit<DialogRoot
    * Useful when the dialog's animation is controlled by an external library.
    * - `close`: Closes the dialog imperatively when called.
    */
-  actionsRef?: React.RefObject<AlertDialogRoot.Actions | null>;
+  actionsRef?: React.RefObject<AlertDialogRoot.Actions | null> | undefined;
   /**
    * A handle to associate the alert dialog with a trigger.
    * If specified, allows external triggers to control the alert dialog's open state.
    * Can be created with the AlertDialog.createHandle() method.
    */
-  handle?: DialogHandle<Payload>;
+  handle?: DialogHandle<Payload> | undefined;
 }
 export type AlertDialogRootActions = DialogRoot.Actions;
 export type AlertDialogRootChangeEventReason = DialogRoot.ChangeEventReason;

package/alert-dialog/root/AlertDialogRoot.js

@@ -34,16 +34,18 @@ function AlertDialogRoot(props) {
   const nested = Boolean(parentDialogRootContext);
   const store = (0, _useRefWithInit.useRefWithInit)(() => {
     return handle?.store ?? new _DialogStore.DialogStore({
-      open: openProp ?? defaultOpen,
-      activeTriggerId: triggerIdProp !== undefined ? triggerIdProp : defaultTriggerIdProp,
+      open: defaultOpen,
+      openProp,
+      activeTriggerId: defaultTriggerIdProp,
+      triggerIdProp,
       modal: true,
       disablePointerDismissal: true,
       nested,
       role: 'alertdialog'
     });
   }).current;
-  store.useControlledProp('open', openProp, defaultOpen);
-  store.useControlledProp('activeTriggerId', triggerIdProp, defaultTriggerIdProp);
+  store.useControlledProp('openProp', openProp);
+  store.useControlledProp('triggerIdProp', triggerIdProp);
   store.useSyncedValue('nested', nested);
   store.useContextCallback('onOpenChange', onOpenChange);
   store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);

package/autocomplete/index.parts.d.ts

@@ -18,4 +18,5 @@ export { ComboboxRow as Row } from "../combobox/row/ComboboxRow.js";
 export { ComboboxCollection as Collection } from "../combobox/collection/ComboboxCollection.js";
 export { ComboboxEmpty as Empty } from "../combobox/empty/ComboboxEmpty.js";
 export { Separator } from "../separator/Separator.js";
-export { useCoreFilter as useFilter } from "../combobox/root/utils/useFilter.js";
+export { useCoreFilter as useFilter } from "../combobox/root/utils/useFilter.js";
+export { useFilteredItems } from "../combobox/root/utils/useFilteredItems.js";

package/autocomplete/index.parts.js

@@ -129,6 +129,12 @@ Object.defineProperty(exports, "useFilter", {
     return _useFilter.useCoreFilter;
   }
 });
+Object.defineProperty(exports, "useFilteredItems", {
+  enumerable: true,
+  get: function () {
+    return _useFilteredItems.useFilteredItems;
+  }
+});
 var _AutocompleteRoot = require("./root/AutocompleteRoot");
 var _AutocompleteValue = require("./value/AutocompleteValue");
 var _ComboboxTrigger = require("../combobox/trigger/ComboboxTrigger");
@@ -149,4 +155,5 @@ var _ComboboxRow = require("../combobox/row/ComboboxRow");
 var _ComboboxCollection = require("../combobox/collection/ComboboxCollection");
 var _ComboboxEmpty = require("../combobox/empty/ComboboxEmpty");
 var _Separator = require("../separator/Separator");
-var _useFilter = require("../combobox/root/utils/useFilter");
+var _useFilter = require("../combobox/root/utils/useFilter");
+var _useFilteredItems = require("../combobox/root/utils/useFilteredItems");

package/autocomplete/root/AutocompleteRoot.d.ts

@@ -20,7 +20,7 @@ export declare function AutocompleteRoot<ItemValue>(props: Omit<AutocompleteRoot
    * The items to be displayed in the list.
    * Can be either a flat array of items or an array of groups with items.
    */
-  items?: readonly ItemValue[];
+  items?: readonly ItemValue[] | undefined;
 }): React.JSX.Element;
 export type AutocompleteRootState = AriaCombobox.State;
 export interface AutocompleteRootActions {
@@ -30,7 +30,7 @@ export type AutocompleteRootChangeEventReason = AriaCombobox.ChangeEventReason;
 export type AutocompleteRootChangeEventDetails = AriaCombobox.ChangeEventDetails;
 export type AutocompleteRootHighlightEventReason = AriaCombobox.HighlightEventReason;
 export type AutocompleteRootHighlightEventDetails = AriaCombobox.HighlightEventDetails;
-export interface AutocompleteRootProps<ItemValue> extends Omit<AriaCombobox.Props<ItemValue, 'none'>, 'selectionMode' | 'selectedValue' | 'defaultSelectedValue' | 'onSelectedValueChange' | 'fillInputOnItemPress' | 'itemToStringValue' | 'isItemEqualToValue' | 'inputValue' | 'defaultInputValue' | 'onInputValueChange' | 'autoComplete' | 'itemToStringLabel' | 'autoHighlight' | 'keepHighlight' | 'highlightItemOnHover' | 'actionsRef' | 'onOpenChange'> {
+export interface AutocompleteRootProps<ItemValue> extends Omit<AriaCombobox.Props<ItemValue, 'none'>, 'selectionMode' | 'selectedValue' | 'defaultSelectedValue' | 'onSelectedValueChange' | 'fillInputOnItemPress' | 'itemToStringValue' | 'isItemEqualToValue' | 'inputValue' | 'defaultInputValue' | 'onInputValueChange' | 'autoComplete' | 'formAutoComplete' | 'itemToStringLabel' | 'autoHighlight' | 'keepHighlight' | 'highlightItemOnHover' | 'actionsRef' | 'onOpenChange' | 'openOnInputClick'> {
   /**
    * Controls how the autocomplete behaves with respect to list filtering and inline autocompletion.
    * - `list` (default): items are dynamically filtered based on the input value. The input value does not change based on the active item.
@@ -39,62 +39,62 @@ 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';
+  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';
+  autoHighlight?: (boolean | 'always') | undefined;
   /**
    * Whether the highlighted item should be preserved when the pointer leaves the list.
    * @default false
    */
-  keepHighlight?: boolean;
+  keepHighlight?: boolean | undefined;
   /**
    * Whether moving the pointer over items should highlight them.
    * Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
    * @default true
    */
-  highlightItemOnHover?: boolean;
+  highlightItemOnHover?: boolean | undefined;
   /**
    * The uncontrolled input value of the autocomplete when it's initially rendered.
    *
    * To render a controlled autocomplete, use the `value` prop instead.
    */
-  defaultValue?: AriaCombobox.Props<React.ComponentProps<'input'>['defaultValue'], 'none'>['defaultInputValue'];
+  defaultValue?: AriaCombobox.Props<React.ComponentProps<'input'>['defaultValue'], 'none'>['defaultInputValue'] | undefined;
   /**
    * The input value of the autocomplete. Use when controlled.
    */
-  value?: AriaCombobox.Props<React.ComponentProps<'input'>['value'], 'none'>['inputValue'];
+  value?: AriaCombobox.Props<React.ComponentProps<'input'>['value'], 'none'>['inputValue'] | undefined;
   /**
    * Event handler called when the input value of the autocomplete changes.
    */
-  onValueChange?: (value: string, eventDetails: AutocompleteRootChangeEventDetails) => void;
+  onValueChange?: ((value: string, eventDetails: AutocompleteRootChangeEventDetails) => void) | undefined;
   /**
    * Whether clicking an item should submit the autocomplete's owning form.
    * By default, clicking an item via a pointer or <kbd>Enter</kbd> key does not submit the owning form.
    * Useful when the autocomplete is used as a single-field form search input.
    * @default false
    */
-  submitOnItemClick?: AriaCombobox.Props<ItemValue, 'none'>['submitOnItemClick'];
+  submitOnItemClick?: AriaCombobox.Props<ItemValue, 'none'>['submitOnItemClick'] | undefined;
   /**
    * When the item values are objects (`<Autocomplete.Item value={object}>`), this function converts the object value to a string representation for both display in the input and form submission.
    * If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
    */
-  itemToStringValue?: (itemValue: ItemValue) => string;
+  itemToStringValue?: ((itemValue: ItemValue) => string) | undefined;
   /**
    * A ref to imperative actions.
    * - `unmount`: When specified, the autocomplete will not be unmounted when closed.
    * Instead, the `unmount` function must be called to unmount the autocomplete manually.
    * Useful when the autocomplete's animation is controlled by an external library.
    */
-  actionsRef?: React.RefObject<AutocompleteRootActions | null>;
+  actionsRef?: React.RefObject<AutocompleteRootActions | null> | undefined;
   /**
    * Event handler called when the popup is opened or closed.
    */
-  onOpenChange?: (open: boolean, eventDetails: AutocompleteRootChangeEventDetails) => void;
+  onOpenChange?: ((open: boolean, eventDetails: AutocompleteRootChangeEventDetails) => void) | undefined;
   /**
    * Callback fired when an item is highlighted or unhighlighted.
    * Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.
@@ -103,7 +103,12 @@ export interface AutocompleteRootProps<ItemValue> extends Omit<AriaCombobox.Prop
    * - `'pointer'`: the highlight changed due to pointer hovering.
    * - `'none'`: the highlight changed programmatically.
    */
-  onItemHighlighted?: (highlightedValue: ItemValue | undefined, eventDetails: AutocompleteRootHighlightEventDetails) => void;
+  onItemHighlighted?: ((highlightedValue: ItemValue | undefined, eventDetails: AutocompleteRootHighlightEventDetails) => void) | undefined;
+  /**
+   * Whether the popup opens when clicking the input.
+   * @default false
+   */
+  openOnInputClick?: boolean | undefined;
 }
 export declare namespace AutocompleteRoot {
   type Props<ItemValue> = AutocompleteRootProps<ItemValue>;

package/autocomplete/root/AutocompleteRoot.js

@@ -65,21 +65,19 @@ function AutocompleteRoot(props) {
     if (other.filter) {
       return other.filter;
     }
-    return (item, query, toString) => {
-      return collator.contains((0, _resolveValueLabel.stringifyAsLabel)(item, toString), query);
-    };
-  }, [other, collator]);
+    return collator.contains;
+  }, [other.filter, collator]);
   const resolvedQuery = String(isControlled ? value : internalValue).trim();
 
   // In "both", wrap filtering to use only the typed value, ignoring the inline value.
   const resolvedFilter = React.useMemo(() => {
     if (mode !== 'both') {
-      return staticItems ? null : other.filter;
+      return staticItems ? null : baseFilter;
     }
     return (item, _query, toString) => {
       return baseFilter(item, resolvedQuery, toString);
     };
-  }, [baseFilter, mode, other.filter, resolvedQuery, staticItems]);
+  }, [baseFilter, mode, resolvedQuery, staticItems]);
   const handleItemHighlighted = (0, _useStableCallback.useStableCallback)((highlightedValue, eventDetails) => {
     props.onItemHighlighted?.(highlightedValue, eventDetails);
     if (eventDetails.reason === _reasons.REASONS.pointer) {

package/avatar/fallback/AvatarFallback.d.ts

@@ -1,6 +1,7 @@
 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";
 /**
  * Rendered when the image fails to load or when no image is provided.
  * Renders a `<span>` element.
@@ -8,12 +9,16 @@ import type { AvatarRoot } from "../root/AvatarRoot.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 AvatarFallbackProps extends BaseUIComponentProps<'span', AvatarRoot.State> {
+export interface AvatarFallbackState extends AvatarRoot.State {
+  transitionStatus: TransitionStatus;
+}
+export interface AvatarFallbackProps extends BaseUIComponentProps<'span', AvatarFallback.State> {
   /**
    * How long to wait before showing the fallback. Specified in milliseconds.
    */
-  delay?: number;
+  delay?: number | undefined;
 }
 export declare namespace AvatarFallback {
+  type State = AvatarFallbackState;
   type Props = AvatarFallbackProps;
 }

package/avatar/fallback/AvatarFallback.js

@@ -11,6 +11,14 @@ 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.
@@ -29,22 +37,42 @@ 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));
     }
     return timeout.clear;
   }, [timeout, delay]);
-  const state = React.useMemo(() => ({
-    imageLoadingStatus
-  }), [imageLoadingStatus]);
+  const state = {
+    imageLoadingStatus,
+    transitionStatus
+  };
+  (0, _useOpenChangeComplete.useOpenChangeComplete)({
+    open: visible,
+    ref: fallbackRef,
+    onComplete() {
+      if (!visible) {
+        setMounted(false);
+      }
+    }
+  });
   const element = (0, _useRenderElement.useRenderElement)('span', componentProps, {
     state,
-    ref: forwardedRef,
+    ref: [forwardedRef, fallbackRef],
     props: elementProps,
-    stateAttributesMapping: _stateAttributesMapping.avatarStateAttributesMapping,
-    enabled: imageLoadingStatus !== 'loaded' && delayPassed
+    stateAttributesMapping,
+    enabled: mounted
   });
+  if (!mounted) {
+    return null;
+  }
   return element;
 });
 if (process.env.NODE_ENV !== "production") AvatarFallback.displayName = "AvatarFallback";

package/avatar/image/AvatarImage.d.ts

@@ -1,6 +1,7 @@
 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 { ImageLoadingStatus } from "./useImageLoadingStatus.js";
 /**
  * The image to be displayed in the avatar.
@@ -9,12 +10,16 @@ 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 AvatarImageProps extends BaseUIComponentProps<'img', AvatarRoot.State> {
+export interface AvatarImageState extends AvatarRoot.State {
+  transitionStatus: TransitionStatus;
+}
+export interface AvatarImageProps extends BaseUIComponentProps<'img', AvatarImage.State> {
   /**
    * Callback fired when the loading status changes.
    */
-  onLoadingStatusChange?: (status: ImageLoadingStatus) => void;
+  onLoadingStatusChange?: ((status: ImageLoadingStatus) => void) | undefined;
 }
 export declare namespace AvatarImage {
+  type State = AvatarImageState;
   type Props = AvatarImageProps;
 }

package/avatar/image/AvatarImage.js

@@ -12,7 +12,15 @@ var _useIsoLayoutEffect = require("@base-ui/utils/useIsoLayoutEffect");
 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");
 var _useImageLoadingStatus = require("./useImageLoadingStatus");
+const stateAttributesMapping = {
+  ..._stateAttributesMapping.avatarStateAttributesMapping,
+  ..._stateAttributesMapping2.transitionStatusMapping
+};
+
 /**
  * The image to be displayed in the avatar.
  * Renders an `<img>` element.
@@ -33,6 +41,13 @@ const AvatarImage = exports.AvatarImage = /*#__PURE__*/React.forwardRef(function
     referrerPolicy,
     crossOrigin
   });
+  const isVisible = imageLoadingStatus === 'loading' || imageLoadingStatus === 'loaded';
+  const {
+    mounted,
+    transitionStatus,
+    setMounted
+  } = (0, _useTransitionStatus.useTransitionStatus)(isVisible);
+  const imageRef = React.useRef(null);
   const handleLoadingStatusChange = (0, _useStableCallback.useStableCallback)(status => {
     onLoadingStatusChangeProp?.(status);
     context.setImageLoadingStatus(status);
@@ -42,16 +57,30 @@ const AvatarImage = exports.AvatarImage = /*#__PURE__*/React.forwardRef(function
       handleLoadingStatusChange(imageLoadingStatus);
     }
   }, [imageLoadingStatus, handleLoadingStatusChange]);
-  const state = React.useMemo(() => ({
-    imageLoadingStatus
-  }), [imageLoadingStatus]);
+  const resolvedTransitionStatus = imageLoadingStatus === 'loading' ? 'starting' : transitionStatus;
+  const state = {
+    imageLoadingStatus,
+    transitionStatus: resolvedTransitionStatus
+  };
+  (0, _useOpenChangeComplete.useOpenChangeComplete)({
+    open: isVisible,
+    ref: imageRef,
+    onComplete() {
+      if (!isVisible) {
+        setMounted(false);
+      }
+    }
+  });
   const element = (0, _useRenderElement.useRenderElement)('img', componentProps, {
     state,
-    ref: forwardedRef,
+    ref: [forwardedRef, imageRef],
     props: elementProps,
-    stateAttributesMapping: _stateAttributesMapping.avatarStateAttributesMapping,
-    enabled: imageLoadingStatus === 'loaded'
+    stateAttributesMapping,
+    enabled: mounted
   });
+  if (!mounted) {
+    return null;
+  }
   return element;
 });
 if (process.env.NODE_ENV !== "production") AvatarImage.displayName = "AvatarImage";