mui/base-ui v1.0.0-beta.3

on GitHub

Sep 3, 2025

General changes

• Breaking change: Base UI event details.
  Custom event callbacks provide BaseUIEventDetails object as their second parameter.
  This object contains the source event, reason and methods to customize the behavior (where applicable).
  For example, onOpenChange(open, event, reason) becomes onOpenChange(open, eventDetails), where eventDetails contains event and reason properties.

  -onOpenChange: (open, event, reason) => {
  -  if (reason === 'escape-key') {
  +onOpenChange: (open, eventDetails) => {
  +  if (eventDetails.reason === 'escape-key') {
       // ...
     }
   }

  (#2382) by @atomiks

Alert Dialog

• Breaking change: Support initialFocus and finalFocus functions.
  The initialFocus and finalFocus props can be functions that return DOM elements to focus.
  This is a new feature for finalFocus and a breaking change for initialFocus as the element must be returned directly (not as a ref).
  (#2536) by @atomiks

Autocomplete

• New Autocomplete component (#2105) by @atomiks

Checkbox

• Fix missing validity attributes when wrapped in Field (#2572) by @Copilot

Combobox

• New Combobox component (#2105) by @atomiks

Context Menu

• Fix default offsets when align="center" or side differs (#2601) by @atomiks

Dialog

• Breaking change: Support initialFocus and finalFocus functions.
  The initialFocus and finalFocus props can be functions that return DOM elements to focus.
  This is a new feature for finalFocus and a breaking change for initialFocus as the element must be returned directly (not as a ref).
  (#2536) by @atomiks
• Restore focus to popup when focused element is removed (#2479) by @atomiks

Field

• Prevent defaultValue reset on focus for uncontrolled inputs (#2543) by @ingokpp
• Allow onValueChange to fire when defaultValue/value are not set (#2600) by @atomiks

Input

• Allow onValueChange to fire when defaultValue/value are not set (#2600) by @atomiks

Menu

• Breaking change: Fix closeParentOnEsc default value.
  The default value of closeParentOnEsc in Menu.SubmenuRoot is now false.
  When the Esc key is pressed in a Submenu, the Submenu closes, and the focus correctly moves to the SubmenuTrigger.
  (#2493) by @seongminn
• Breaking change: Support initialFocus and finalFocus functions.
  The initialFocus and finalFocus props can be functions that return DOM elements to focus.
  This is a new feature for finalFocus and a breaking change for initialFocus as the element must be returned directly (not as a ref).
  (#2536) by @atomiks
• Fix menu not opening when inside context menu trigger (#2506) by @baptisteArno
• Fix transform-origin variable calculation when Positioner sideOffset is a function (#2511) by @atomiks
• Fix submenu events (#2483) by @atomiks
• Fix limitShift offset based on arrow size (#2571) by @atomiks

Navigation Menu

• Breaking change: Semantic element structure and active page prop.
  NavigationMenu.List renders <ul> and NavigationMenu.Item renders <li> by default.
  (#2526) by @atomiks
• Unshare AbortController instance (#2441) by @tomokinat
• Close on link click by default (#2535) by @atomiks

Number Field

• Fix duplicate onValueChange calls (#2591) by @atomiks

Popover

• Breaking change: Support initialFocus and finalFocus functions.
  The initialFocus and finalFocus props can be functions that return DOM elements to focus.
  This is a new feature for finalFocus and a breaking change for initialFocus as the element must be returned directly (not as a ref).
  (#2536) by @atomiks
• Fix outside click after right clicking in popup (#2508) by @baptisteArno
• Fix unexpected close when nested inside two popovers (#2481) by @atomiks
• Fix transform-origin variable calculation when Positioner sideOffset is a function (#2511) by @atomiks
• Restore focus to popup when focused element is removed (#2479) by @atomiks
• Fix limitShift offset based on arrow size (#2571) by @atomiks

Preview Card

• Fix transform-origin variable calculation when Positioner sideOffset is a function (#2511) by @atomiks
• Fix limitShift offset based on arrow size (#2571) by @atomiks

Radio Group

• Return null in form data when no option selected (#2473) by @ingokpp

Scroll Area

• Prevent pointer events from sibling portals triggering hover (#2542) by @KenanYusuf

Select

• Fix stale items prop (#2397) by @atomiks
• Fix unexpected close when nested inside two popovers (#2481) by @atomiks
• Fix onValueChange type inference (#2372) by @atomiks
• Fix transform-origin variable calculation when Positioner sideOffset is a function (#2511) by @atomiks
• Reset state when selected item is removed (#2577) by @atomiks
• Fix data-highlighted and DOM focus item desync (#2569) by @atomiks
• Fix item click with defaultOpen prop (#2570) by @atomiks
• Fix scroll arrows not propagating scroll fully to start/end of list (#2523) by @atomiks
• Fix limitShift offset based on arrow size (#2571) by @atomiks

Slider

• Breaking change: Instead of the thumb div, the input type="range" element receives focus. Focus styles that were targeting the thumb, should be updated.
  For example .Thumb:focus-visible should be replaced with .Thumb:has(:focus-visible).
  The tabIndex prop is moved from Root to Thumb where it gets forwarded to the input.
  The thumb's render prop no longer contains the third inputProps argument; the input element is instead merged with children.
  (#2578) by @mj12albert
• Reduce bundle size (#2551) by @oliviertassinari
• Fix thumb :focus-visible with mixed keyboard and pointer modality (#2584) by @mj12albert
• Add index prop to Slider.Thumb (#2593) by @mj12albert

Tabs

• Fix tab size rounding (#2488) by @atomiks
• Fix highlight sync when focus is inside list (#2487) by @atomiks

Tooltip

• Fix transform-origin variable calculation when Positioner sideOffset is a function (#2511) by @atomiks
• Fix limitShift offset based on arrow size (#2571) by @atomiks

useRender

• Add support for data-* attributes (#2524) by @Raghuboi
• Add defaultTagName parameter (#2527) by @atomiks

All contributors of this release in alphabetical order: @atomiks, @baptisteArno, @brijeshb42, @Copilot, @ingokpp, @Janpot, @KenanYusuf, @LukasTy, @michaldudak, @mirka, @mj12albert, @mnajdova, @oliviertassinari, @Powerplex, @Raghuboi, @seongminn, @tomokinat