npm / @base-ui/react
@base-ui/react
What changed in @base-ui/react 1, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-19.
14 breaking2 deprecations62 new APIs and options13 performance48 behavior and defaults333 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@base-ui/react 1472 changes
Breaking changes 14
Removed the presentational viewport role.
No longer adds an implicit
dirattribute.Trigger behavior and keyboard navigation are fixed; the region role is removed.
The namespace export is renamed from OTPFieldPreview to OTPField; import it from @base-ui/react/otp-field.
Pressing Enter submits the associated form.
Renames sanitizeValue to normalizeValue and allows composing it with validation.
Drawer is stable rather than preview and should be imported from the drawer entry point.
Swipe CSS variables no longer inherit.
The
Popupcomponent no longer receivesaria-readonlywhenreadOnlyis set.Types
valueas a string to match Toggle.Removes the discriminated props union.
Removes the duplicated disabled prop.
The package was renamed from @base-ui-components/react to @base-ui/react.
A disabled tab is no longer initially selected.
Deprecations 2
Warns when a popup is missing
Viewport.A warning is emitted when a component function is rendered directly.
New APIs and options 62
Exported the CssVariables type for use by developers.
Added an x option to data-base-ui-swipe-ignore.
Added a y option to data-base-ui-swipe-ignore.
Exported the DataAttributes type for use by developers.
Call this from onOpenChange to opt out of automatic unmounting in Autocomplete, Combobox, and Select.
Added preview menu filtering behavior using Menu.FilterProvider, Menu.Input, and onItemHighlighted.
Added preview menu filtering behavior through Menu.FilterProvider.
Added Menu.Input as part of preview menu filtering behavior.
Adds the keepMounted prop.
Adds a collection API for creating items.
Adds a disabled data attribute.
Allows functional toast updates derived from the current toast.
Change event details now include
input-pressandcancel-open.Change event details now include
input-pressandcancel-open.Exposes the
expandedstate for inline comboboxes.Renders content passed through the
renderprop in Toast.Title, Toast.Description, and Toast.Action.A virtual keyboard provider is added.
Exposes the clear visibility state.
Adds data-popup-side to the Select trigger.
Preview Card integrates inline positioning.
The Toast
addmethod now supports upsert.Hidden inputs now expose the
formprop.Adds a preview component for one-time password and verification code entry.
Hidden inputs now support
suppressHydrationWarning.Navigation Menu adds generic
Valuetyping.Accordion adds generic Value typing.
Tooltip adds the closeOnClick prop.
Adds the InputGroup part to Autocomplete and Combobox.
Adds the Label part to Combobox, Select, and Slider.
Drawer adds the SwipeArea part.
Enables closing all toasts.
Combobox adds support for a visually hidden close button and improves modal focus trapping.
Adds the
allowOutOfRangeprop to Number Field.Adds an
autoCompleteprop for explicit browser autofill support in Combobox and Select.Adds transition attributes.
The
onOpenChangereason distinguishesinput-pressfromtrigger-press.Adds a new Drawer / Sheet component.
Adds the
Menu.LinkItempart.Adds the
keepMountedprop to theContentpart.Adds generic
Valuetyping to Radio.Adds the
data-scrollingstate attribute to the Root and Viewport parts.Adds the
data-scrollingstate attribute to the Root and Viewport parts.Adds the
finalFocusprop.Adds transition attributes to the Tabs.Panel part.
Introduces a store.
Adds a hook for filtered items.
Adds the loopFocus prop.
Adds the data-list-empty state attribute.
Adds the data-popup-side state attribute.
Includes ref in BaseUIComponentProps.
Adds the loopFocus prop.
Adds the data-list-empty state attribute.
Adds the data-popup-side state attribute.
Adds the placeholder prop.
Adds CSPProvider.
Adds the actionsRef prop.
Adds the nativeLabel prop.
Adds the actionsRef prop.
Adds support for detached triggers.
Adds the placeholder prop.
Adds the value prop.
Combobox and Select now allow null as an option for the value prop.
Performance 13
Improved mount performance for large lists.
Avoided touch event overhead while the drawer is closed.
Inactive triggers no longer re-render on open and close.
Improved mount performance for large lists.
Registers passive touch listeners.
Improves trigger mount performance.
Popup, store, shared popup, and numerous component bundles are smaller.
The Slider and Tabs prehydration scripts are excluded from client bundles.
Swipe dismissal is more performant, and swipe gestures are driven natively to stop per-frame re-rasterization.
Interaction splitting improves mount performance, including closed popup mounts by up to 50% and unmounting by up to 85%.
Hot paths in useHover hooks and safePolygon are optimized.
Prevents re-renders when
Field.Controlis uncontrolled.Includes performance improvements.
Behavior and default changes 48
Checkbox, Radio Group, and Switch now prefer aria-label over associated labels.
Combobox accepts readonly arrays for multiple values.
Accordion and Collapsible panels expand synchronously on beforematch.
Menu passes the native event to onOpenChange when an item press closes the menu.
Repeated trigger activation toggles submenus.
Renders groups with the rowgroup role in grid mode and hides group labels and scrollbars from the accessibility tree.
Moves aria-orientation to the role owners.
Allows opening and browsing the popup while readOnly.
Moves aria-orientation to the role owners.
Anchors multiple selection to the first selected item with a linear lookup.
Renders groups with the rowgroup role in grid mode and hides group labels and scrollbars from the accessibility tree.
Moves aria-orientation to the role owners.
Hides group labels and scrollbars from the accessibility tree.
Hides group labels and scrollbars from the accessibility tree.
Anchors multiple selection to the first selected item with a linear lookup and hides group labels and scrollbars from the accessibility tree.
Moves aria-orientation to the role owners.
Allows opening and browsing the popup while readOnly.
Filtering resets the list scroll position.
Focuses the first invalid field in document order.
Adds WebKit overscroll feedback to the thumb.
Does not force-mount the popup when values change programmatically.
Blur respects Intl rounding options, while numeric precision is preserved with default display formatting.
Supports use inside Menu.RadioGroup.
Allows Persian digits in keyboard input.
Fires for automatic tab selection.
Fires when the full value is pasted.
Supports Ctrl and Cmd shortcuts.
Allows mouse selection without highlighting an item.
Marks date-fns peer dependencies as optional.
Skips client-only prehydration scripts.
Skips client-only prehydration scripts.
Keeps the viewport expanded while touch swiping.
Anchor width and height are snapped to the device pixel grid.
Checkbox, Radio Group, and Switch add automatic aria-labelledby support.
Parent menus close when a nested link with closeOnClick is clicked.
The attribute is applied to the highest-level node.
Menu content transitions are implemented with Viewport.
Popover traps focus when Popover.Close is rendered inside and modal is true, and supports a visually hidden close button.
Exit animations are allowed when
keepMounted={false}.Makes
createToastManagera generic function.The render prop supports lazy elements.
Enables Home/End key navigation.
Makes
useToastManagera generic function.Makes mergeProps public.
With detached triggers, specifying positioner width and height CSS variables is no longer necessary unless the Viewport part is included.
With detached triggers, specifying positioner width and height CSS variables is no longer necessary unless the Viewport part is included.
Toggle Group is more permissive toward falsy toggle values.
Submenus now allow side axis fallback by default.
Fixes and other changes 333
Fixed the data-index attribute on Accordion.Trigger.
Fixed the data-value attribute on Accordion.Trigger.
Native buttons used as Accordion.Trigger now receive the native disabled attribute.
Animation waits no longer retain detached elements.
Fixed autoHighlight for asynchronous Autocomplete and Combobox results.
Drawer handles CloseWatcher close requests from the cancel event.
Closing completes when a render function removes the panel.
Animations are restored when a removed panel reopens.
Native buttons used as Collapsible.Trigger now receive the native disabled attribute.
Fixed stale chip focus after returning to the input.
Closing a nested dialog in a closed shadow root keeps the parent open.
Fixed native focus scrolling on iOS 27.
Item taps are preserved when dismissing the virtual keyboard.
Scrolling replaces swiping when a drag starts on an SVG.
Preserved release velocity after a trailing stationary pointer event and fixed velocity on 120 Hz input.
Removed excess virtual keyboard scroll space and avoided excess keyboard spacing in Chrome on iOS.
Unmounted drawers are no longer retained in Drawer.Provider.
Avoided warnings when an uncontrolled Field.Control defaultValue changes.
Fixed stale focused field state.
Fixed hover-out animations when switching between detached triggers in Menu and Popover.
Corrected inputRef forwarding and cleanup in Radio Group.
Item registration stays in sync when items change under Strict Mode.
Fixed the focus guard loop when the trigger is the only tabbable element.
Parent menu subscriptions are released when a submenu unmounts.
Fixed event listener cleanup in Menu.Trigger.
onClick now fires once per click.
The callback receives the originating event; pointer events may be MouseEvent or PointerEvent, and typing reports the reason none.
A popup opened programmatically is no longer associated with a trigger that did not open it.
Ignored arrow keys no longer select an option on refocus.
Transition state stays consistent when reopening a retained popup in Menu and Popover.
Fixed Safari IME composition over-filling OTP Field slots.
Fixed label focus in Shadow DOM for Combobox, Field, Select, and Slider.
Single-element array values are preserved on pointer interaction.
Slider drags now end on touchcancel and pointercancel.
Fixed onValueCommitted not firing for touch track taps.
A submenu closes when focus returns through its guard.
Fixed selecting tabs with function values.
Toast timers remain paused during overlapping interactions.
Typeahead state resets when closing without moving focus in Combobox, Menu, and Select.
A viewport transition no longer starts when a trigger remounts while closed in Menu, Popover, Preview Card, and Tooltip.
Ignores outside clicks from presses that began before the dialog opened.
Fixes stale and duplicated control IDs, controlled blur validation, and stale filled state.
Fixes stale and duplicated control IDs.
Fixes applying data-readonly to Combobox.Trigger.
Fixes cancellation when preserving the filter after selection and record item label lookup reading from Object.prototype.
Fixes label association when a control unregisters.
Ignores outside clicks from presses that began before the dialog opened.
Fixes disabled anchor tracking on scroll.
Ignores swipes without an attributed direction when using snap points, respects canceled snap point dismissal, and ignores the page scroller when starting a swipe.
Fixes custom validity ownership and validation lifecycle, controlled value synchronization, control IDs, Enter validation, async validity, and controlled blur validation.
Prevents clearErrors from dropping updates when multiple fields change at once.
Fixes hover and focus interaction issues.
Fixes prop and ref merging for lazy render elements.
Plays the enter transition for an initially open submenu.
Fixes the accessibility tree to satisfy aria-required-children.
Fixes pointer-events locking when sweeping quickly across a trigger and keeps focus on the trigger when opening.
Stops incrementing when disabled during press-and-hold, prevents scrubbing on horizontal wheel events, and preserves native and consumer-controlled selection when focusing the input.
Ignores outside clicks from presses that began before the popover opened.
Fixes detached trigger store migration.
Fixes roving focus when items are added or removed.
Prevents scrollbars from stealing focus.
Fixes the root ID being ignored inside a Field and record item label lookup reading from Object.prototype.
Prevents update loops from unstable refs.
Fixes controlled blur validation and stale filled state.
Prevents update loops from unstable refs and considers 3D transforms when positioning the indicator.
Respects the trigger delay when the provider delay is zero.
Improves transform origin for start/end alignment.
Filtering respects the current locale.
Keeps focus on the invalid OTP field when auto-submit is blocked.
Renders immediately when
delay={0}.Aligns submitted form values with native form submission.
Corrects an off-by-one error on the biased side.
Inherits the disabled state from
Combobox.Root.Grouped items stop being filtered after the configured limit.
Inline comboboxes receive an initial highlight and return the highlight to the selected item when the query is cleared.
Corrects dirty-state tracking for controls with null values.
Does not reopen after remounting with a reused handle.
Fixes unreliable swipe-to-open gestures and several swipe, scrolling, and snap-point issues.
Disabled fields retain their invalid state.
Visible focus is restored after keyboard close in Safari and Firefox.
Corrects separator semantics in listboxes.
Submenus open on Android TalkBack press.
Propagates disabled state to menu items.
Fixes keyboard editing with multi-character format symbols.
Unpositioned popups stay at the viewport origin, and auto-resize uses the correct origin for left-anchored popups.
Custom
minandmaxsemantics now match the indicator.Aligns submitted form values with native form submission.
Removes unnecessary ARIA attributes.
Types callback props based on the element being rendered.
Inherits the disabled state from
Select.Root.Fixes assorted Slider issues.
Positions the pre-hydration indicator inside streamed Suspense.
Keyboard navigation is aligned with APG and trigger behavior bugs are fixed.
Programmatic focus return is fixed.
In grid mode, ArrowLeft and ArrowRight stay on the input caret.
Image status edge cases are fixed.
Group cancellation, indeterminate state, custom validation, multiple-required validation, and group ID forwarding are fixed.
Parent group cancellation, indeterminate state, disabled focus attributes, and extra validation calls are fixed.
Trigger and panel state bugs are fixed.
Items no longer all re-render on every keystroke; grid-mode caret handling and autofill and selected-state edge cases are also fixed.
A chip context error is fixed.
Focus return, positioning, viewport edge cases, non-modal focus-out closing, and tabindex management are fixed.
Swipe commits on primary-button release.
Form validation and valueMissing revalidation bugs are fixed; disabled Field.Item state is reflected in labels and descriptions.
Disabled fieldset form bugs are fixed.
Form validation bugs are fixed.
Viewport morphing is restored after reopening kept-mounted popups.
Submenu trigger interactions and controlled hover-leave closing are fixed; submenus open on hover after a plain delay, and positioning edge cases are fixed.
Vertical menu focus behavior is fixed.
Value text stays synchronized with the indicator.
Controlled exit transitions are preserved, and interaction, value, and styling-hook bugs are fixed.
Clipboard paste, committed values, keyboard stepping, formatter locale caching, input, and scrub edge cases are fixed.
Password manager bubbles are avoided after the first input.
Controlled hover-leave closing, programmatic focus return, positioning, viewport edge cases, non-modal focus-out closing, and tabindex management are fixed.
Inline previews stay anchored while open, and the card closes when its active trigger unmounts.
Controlled hover-leave closing and positioning edge cases are fixed.
Group IDs are forwarded; Space-key selection, disabled selected form submission, and canceled value changes are fixed.
Scrolling state is added to Thumb, and overflow and scrolling state bugs are fixed.
Autofill and selected-state edge cases, multiple-mode dirty-state clearing, disabled-item typeahead, and multiple-mode serialization are fixed.
Interaction edge cases, extra validation calls, and touchend listener accumulation are fixed.
Hook values now update when the store or arguments change.
Extra validation function calls are fixed.
State edge cases and suspended panel activation are fixed.
Timer and limit edge cases are fixed.
Grouped cancellation behavior is fixed.
Grouped cancellation, disabled state, and roving focus bugs are fixed; invalid aria-orientation is removed from the role=group element.
The default toolbar button no longer receives disabled, and disabled state and roving focus bugs are fixed.
Positioning and viewport edge cases, provider delay group lifecycle, and preventUnmountOnClose reopening behavior are fixed; the tooltip closes when its active trigger unmounts.
Fixes handle defaults.
Fixes native FormData handling for popup inputs.
Preserves closeQuery when closing a multiple-input Combobox with inputs inside its popup.
Fixes form submission from popup inputs.
Fixes right-to-left component behavior.
Ignores hidden-input changes while the component is readonly or disabled.
Open state detection considers the controlled open prop.
Forwards the style prop.
Avoids flushSync during validation.
Avoids flushSync during validation.
Does not take initial focus if focus has already moved inside a popup.
Fixes submenu pointer-events scope for keepMounted portals.
Open state detection considers the controlled open prop.
Fixes right-to-left component behavior.
Fixes keepMounted content sizing.
Synchronizes pasted input during step interactions.
Fixes vertical arrow slot navigation.
Ignores hidden input changes while the field is readonly or disabled.
Prevents locked hidden autofill validation.
Fixes right-to-left arrow navigation.
Fixes right-to-left component behavior.
Preserves the active trigger on close press.
Open state detection considers the controlled open prop.
Fixes macOS Safari and Firefox minimizing fullscreen when closing popups with Escape.
Open state detection considers the controlled open prop.
Fixes return focus when the reference disconnects.
Fixes right-to-left component behavior.
Clears stale item text refs.
Ignores hidden-input changes while the component is readonly or disabled.
Fixes nested Select requiring extra outside clicks to dismiss its parent.
Fixes stuck drag state on release.
Open state detection considers the controlled open prop.
Fixes flickering when nesting a tooltip inside another tooltip's trigger.
Virtual arrows use the local document.
Fixes tabbability for elements using display: contents.
Fixes forwarding of event handlers that receive multiple arguments.
Fixes stale popup sizing when the trigger is hovered rapidly.
Clears the highlight on pointer leave when an item is clipped by a scroll container.
Fixes detached trigger HMR when handles are recreated.
Fixes RTL-aligned popup positioning when this option is used.
Removes an invalid
aria-orientationattribute from Navigation Menu.Fixes initial live region announcements.
Fixes a flash when the image is cached.
Fixes uncontrolled default initialization.
Input state no longer changes in read-only mode.
Clicks in Chips areas now focus the input or open the popup.
Fixes an uncaught TypeError when converting a circular structure to JSON.
Fixes open state when
keepMountedis used without transitions.Fixes browser autofill with object values when autofill uses the label.
Item taps no longer blur the input.
Keyboard navigation now respects rendered chips.
Fixes initial live region announcements.
Prevents scroll lock when a controlled value triggers a re-render.
Fixes iOS viewport settling.
Fixes detached trigger HMR when handles are recreated.
Prevents dialogs from affecting a nested drawer stack.
Fixes nested swipe cancel state.
Fixes cleanup after an interrupted swipe dismissal.
Fixes touch scrolling in portaled popups.
Fixes form error matching.
Clicks in InputGroup areas now focus the input or open the popup.
Preserves dialog focus on pointer leave.
Full-width anchored modal popups lock scroll with touch input.
Fixes nested inline submenu hover handoff.
Fixes top-level trigger pointer events blocking.
Fixes reverse Shift+Tab submenu re-entry.
Fixes transition width when reopening.
Fixes the initial trigger switch size snap.
Fixes format rounding error on blur.
Fixes outside-press dismissal in a shared shadow root.
Synchronizes hover open event state.
Removes stray focus guards around the trigger when modal.
Repositions to a different trigger when reopened with
keepMounted.Fixes runtime wrapping of the handler.
Fixes hover reopen race conditions across close transitions.
Render prop warnings are more accurate.
Fixes browser autofill with object values when autofill uses the label.
Fixes scroll arrows stopping short of the edges.
Preserves touch exit animations.
Fixes touch reopen highlight.
Fixes keyboard floating-point rounding.
Removes extra TalkBack focus targets.
Fixes edge thumb alignment after reveal.
Now respects disabled state supplied through
render.Input state no longer changes in read-only mode.
Fixes activation direction on first render.
Fixes
activationDirectionnot updating on programmatic value changes.Fixes timers not resuming after the window regains focus.
Fixes incorrect keyboard navigation on the cross axis.
Fixes the fallback with browser zoom.
Fixes duplicate aria-orientation attributes.
Fallback transition logic is removed to prevent premature image display.
Field attributes are no longer applied to an input inside the popup.
Fixes ARIA attributes during server-side rendering.
Fixes wrapping in virtualized grid arrow-key navigation.
Ignores mouseup on non-Mac platforms.
The attribute is explicit for touch interactions.
Fixes React 17 support.
Touch selection is improved and cross-axis scrolling is preserved during touch gestures.
Combobox preserves inline input on Enter when nothing is highlighted.
Fixes field validation when Form errors and the invalid prop are present at the same time.
Autocomplete respects a null filter prop.
The frontmost height variable includes the border.
Fixes the hidden input id fallback in Select.
Fixes the Select items type definition for groups.
Composite widgets skip CSS-hidden items during keyboard navigation.
Fixes closeDelay not being applied to Menu.SubmenuTrigger.
Fixes support for nested inline menus and close propagation in nested hover menus.
Fixes delayed trigger switches in Safari.
Fixes behavior for nested hoverable popups.
Fixes label announcements in NVDA for Meter and Progress.
Select fires onClick during drag-to-select.
Prevents duplicate onClose calls for ending toasts.
Fixes increment and decrement press reason values in Number Field onValueCommitted.
The value resets after the close transition.
Outside press dismissal works when a component is portaled into a shadow DOM.
Menu pointerleave no longer steals focus from dialogs.
Portable types are fixed.
Fixes focus trapping with a non-scrollable viewport and thumb size after remounting.
Composite widgets fire Space activation on keydown.
Drawer swipe dismissal is prevented when the component is controlled.
The indicator position is re-rendered when a tab resizes.
Slider stops committing validation on touchend.
Fixes Value placeholder rendering with Record items.
Fixes the popup closing on iOS VoiceOver.
Autocomplete uses its internal filter method when
modeislist.Fixes autofocus in SSR environments for Field and Input.
Modifier key properties are preserved in the change event.
A disabled
Chipno longer receives focus.The
Clearcomponent no longer receivesaria-readonlywhenreadOnlyis set.Fixes explicit
collisionAvoidancewithside: 'flip'not working in Context Menu.The selected value is no longer cleared when its item is absent from the items array.
Fixes handling of async items while the popup is open.
Fixes the
disabledprop not working.Fixes a max update depth loop when using
<React.Activity>.Updates the ref type to
HTMLElement.Stops repeating changes at bounds.
Fixes pen pointer handling.
Fixes missing field state data attributes.
Fixes a missing
aria-ownselement.Fixes a flash at the origin before positioning completes in Preact.
Modifier key properties are preserved in the change event.
Exit animations are allowed when
keepMounted={false}.Fixes a page scroll jump when an input with focus unmounts in Safari.
Fixes
highlightItemOnHovernot being respected.Resets typeahead on external blur.
Fixes missing field state data attributes.
Modifier key properties are preserved in the change event.
Improves type safety and inference.
Prevents opening when focusing a disabled Trigger and fixes the disabled prop on Triggers.
Fixes keyboard navigation with non-interactive trigger elements.
Allows actionsRef to be null.
Fixes the hidden input id and required props.
Fixes the hidden input id and required props.
Forwards the root id to the visible form element.
Adds the toolbar role to prevent NVDA from entering browse mode.
Fixes the controlled value prop when items change.
Fixes label resolution for multiple values.
Avoids creating sibling elements next to the trigger.
Fixes detached trigger remounting.
Fixes the Dialog.Title forwardedRef type.
Fixes a Maximum update depth exceeded error with Suspense.
Field onBlur handlers are not triggered when opening the popup.
Field onBlur handlers are not triggered when opening the popup.
Adds a missing type export.
Fixes forwarded ref types.
Avoids disabling modality on click after the menu opens on hover.
Fixes focus guard handling.
Fixes submenu outside-press dismissal on touch.
Clicking and dragging outside a nested popup no longer closes its parent popups.
Fixes the Field data-focused state.
Fixes hidden input focus on submit.
Fixes the timing of onOpenChangeComplete(true).
Fixes touch openMethod when tapping outside element bounds on Safari.
Prevents disabling focus management when clicking the trigger before the hover delay completes.
Fixes popup auto resize glitches.
Fixes focus guard handling.
Fixes the hidden input id and required props.
Fixes the value type.
Fixes support for transform animations when alignItemWithTrigger is active.
Fixes support for max-height popup styles when alignItemWithTrigger is active.
Fixes support for individual transform animations when alignItemWithTrigger is active.
Fixes the data-filled state in multiple mode.
Prevents highlight removal on popup mouseout when highlightItemOnHover is disabled.
Forwards the root id to the visible form element.
Fixes label resolution for multiple values.
Ensures onValueCommitted is called for range sliders.
Fixes the hidden input id and required props.
Fixes timers not being rescheduled when updated.
Fixes trackCursorAxis handling.
Fixes popup auto resize glitches.
Exports missing types.
Fixes visually hidden input styles across form components.
Fixed a development error when a toast is added.
Fixed indicator positioning in transformed containers.
Combobox and Select now respect itemToStringValue for onFormSubmit.
Focus now returns to the trigger on Esc when the pointer rests on the popup.
Fixed the ignored modal setting in the Popovers experiment.
Fixed the open method always being null.
Fixed mount transitions on Positioner in Firefox for Navigation Menu, Popover, and Tooltip.
Fixed support for multiple scrub areas.
Fixed shared tooltips closing when there are gaps between triggers.
Fixed submenus opening with a 0 delay.
Fixed an aria-hidden warning emitted on click.
Fixed skipped viewport transitions in Popover and Tooltip.