Changelog

0.4.7

New `SelectValue` component

A SelectValue component is now available. This is a value component, which means it doesn't render any DOM elements and, as a result, doesn't take HTML props. Optionally, it can use a fallback prop as a default value if the store's value is undefined:

<Select>
  <SelectValue fallback="Select a value" />
  <SelectArrow />
</Select>
<Select>
  <SelectValue fallback="Select a value" />
  <SelectArrow />
</Select>

Other updates

Added React 19 to peer dependencies.
Fixed autoSelect behavior with virtualized lists on mobile devices.
Improved JSDocs.
Updated dependencies: @ariakit/react-core@0.4.7

0.4.6

Nested `SelectList`

The SelectList component can now be nested within a SelectPopover. This lets you render additional elements inside the popover without breaking the accessibility tree. The ARIA roles will be automatically adjusted to ensure a valid accessibility tree:

<SelectProvider>
  <Select />
  <SelectPopover>
    <SelectHeading>Fruits</SelectHeading>
    <SelectDismiss />
    <SelectList>
      <SelectItem value="Apple" />
      <SelectItem value="Banana" />
    </SelectList>
  </SelectPopover>
</SelectProvider>
<SelectProvider>
  <Select />
  <SelectPopover>
    <SelectHeading>Fruits</SelectHeading>
    <SelectDismiss />
    <SelectList>
      <SelectItem value="Apple" />
      <SelectItem value="Banana" />
    </SelectList>
  </SelectPopover>
</SelectProvider>

New Select components

Two new components have been added to the Select module: SelectHeading and SelectDismiss.

You can use them alongside SelectList to add a heading and a dismiss button to the select popover:

<SelectProvider>
  <Select />
  <SelectPopover>
    <SelectHeading>Fruits</SelectHeading>
    <SelectDismiss />
    <SelectList>
      <SelectItem value="Apple" />
      <SelectItem value="Banana" />
    </SelectList>
  </SelectPopover>
</SelectProvider>
<SelectProvider>
  <Select />
  <SelectPopover>
    <SelectHeading>Fruits</SelectHeading>
    <SelectDismiss />
    <SelectList>
      <SelectItem value="Apple" />
      <SelectItem value="Banana" />
    </SelectList>
  </SelectPopover>
</SelectProvider>

`--popover-transform-origin`

The Popover components now expose a --popover-transform-origin CSS variable. You can use this to set the transform-origin property for the popover content element in relation to the anchor element:

.popover {
  transform-origin: var(--popover-transform-origin);
}
.popover {
  transform-origin: var(--popover-transform-origin);
}

Opening `SelectPopover` on click

To ensure uniformity across all dropdown buttons in the library, the SelectPopover now opens when you click on the Select component, instead of on mouse/touch/pointer down.

This change also resolves a problem where the :active state wouldn't be triggered on the select button due to a focus change on mousedown.

Other updates

Fixed ref warning in React 19.
Ensured Combobox uses roving tabindex to manage focus on mobile Safari.
Added a new listElement state to the Select store.
Improved use of Tab components within Select widgets.
Fixed data-focus-visible being applied after a blur event.
Fixed composite items not scrolling into view in Safari.
Improved JSDocs.
Updated dependencies: @ariakit/react-core@0.4.6

0.4.5

Multi-selectable Combobox with inline autocomplete

When rendering a Multi-selectable Combobox with the autoComplete prop set to "inline" or "both", the completion string will no longer be inserted into the input upon deselecting an item. This is because the completion string generally represents an addition action, whereas deselecting an item is a removal action.

Other updates

Updated Combobox to no longer use ReactDOM.flushSync when updating the value.
Added new resetValueOnSelect prop to ComboboxItem.
Added new resetValue method to combobox store.
Improved JSDocs.
Updated dependencies: @ariakit/react-core@0.4.5

0.4.4

Combobox `autoFocusOnHide` behavior

Previously, the autoFocusOnHide feature on ComboboxPopover was turned off by default. Most of the time, this didn't have any practical impact because the combobox input element was already focused when the popover was hidden.

Now, this feature is enabled by default and should work consistently even when virtualFocus is set to false.

Better SVG strokes

The strokeWidth property on SVG elements rendered by CheckboxCheck, ComboboxCancel, ComboboxDisclosure, DialogDismiss, HovercardDisclosure, PopoverDisclosureArrow, and all components that use any of these now defaults to 1.5px instead of 1.5pt. This should make the strokes slightly thinner.

Remember, you can always override the SVG element rendered by these components by rendering custom children.

Minimum value length to show combobox options

A new showMinLength prop has been added to the Combobox component. This prop lets you set the minimum length of the value before the combobox options appear. The default value is 0.

<Combobox showMinLength={2} />
<Combobox showMinLength={2} />

Previously, achieving this behavior required combining three separate props: showOnChange, showOnClick, and showOnKeyPress. We've added this prop to simplify this common task.

These props continue to work as expected as they can be used to customize the behavior for each distinct event.

Rendering composite items as input elements

We've added the ability to render CompositeItem as an input element using the render prop:

<CompositeItem render={<input />} />
<CompositeItem render={<input />} />

Before, you could only do this with the experimental CompositeInput component. Now, this functionality is integrated directly into the CompositeItem component.

Other updates

Fixed Dialog calling autoFocusOnHide twice.
Improved JSDocs.
Updated dependencies: @ariakit/react-core@0.4.4

0.4.3

Fixed TypeScript types for ref.
Fixed CompositeItem occasionally failing to set the activeId state on focus.
Fixed unmountOnHide prop not working on TabPanel without tabId.
Fixed regression in v0.4.2 that caused nested tabs to stop working.
Added new combobox property to tab store.
Improved JSDocs.
Updated dependencies: @ariakit/react-core@0.4.3

0.4.2

Tooltip behavior improvements

When using Tooltip components alongside elements that move focus upon clicking (like MenuButton, which moves focus to its Menu when clicked), the tooltip will now stop from appearing after the user clicks the anchor element. It will only show when the mouse leaves and re-enters the anchor element.

This was already the case when tooltips had no timeout. Now, the behavior is consistent regardless of the timeout value.

Combobox with Tabs

Tab components can now be rendered as part of other composite widgets, like Combobox. The following structure should work seamlessly:

<ComboboxProvider>
  <Combobox />
  <ComboboxPopover>
    <TabProvider>
      <TabList>
        <Tab />
      </TabList>
      <TabPanel unmountOnHide>
        <ComboboxList>
          <ComboboxItem />
        </ComboboxList>
      </TabPanel>
    </TabProvider>
  </ComboboxPopover>
</ComboboxProvider>
<ComboboxProvider>
  <Combobox />
  <ComboboxPopover>
    <TabProvider>
      <TabList>
        <Tab />
      </TabList>
      <TabPanel unmountOnHide>
        <ComboboxList>
          <ComboboxItem />
        </ComboboxList>
      </TabPanel>
    </TabProvider>
  </ComboboxPopover>
</ComboboxProvider>

Other updates

Fixed inert behavior on older browsers.
Fixed Portal rendering extra span even when the portal prop is false.
Fixed Focusable to identify summary as a native tabbable element.
Added Role.summary component.
Improved typeahead functionality on unmounted composite items.
Added new composite property to tab store.
Added new hideWhenEmpty prop to ComboboxCancel.
Added support for nested ComboboxList.
Added unmountOnHide prop to TabPanel.
Improved JSDocs.
Updated dependencies: @ariakit/react-core@0.4.2

0.4.1

New `autoSelect` mode

The autoSelect prop of the Combobox component now accepts a new "always" value:

<Combobox autoSelect="always" />
<Combobox autoSelect="always" />

When using this value, the first enabled item will automatically gain focus when the list shows up, as well as when the combobox input value changes (which is the behavior of the autoSelect prop when set to true).

`ComboboxItem` losing focus too early

Some tweaks were made to the ComboboxItem component to ensure it doesn't lose focus right after a click or Escape keystroke when the combobox popover is animated. This should avoid an inconsistent UI as the popover plays its exit animation.

Other updates

Added disclosure property to disclosure stores.
Added blurActiveItemOnClick prop to Combobox.
Added showOnClick prop to Combobox.
Added showOnKeyPress prop to Combobox.
Fixed DisclosureContent components losing their ref value on fast refresh.
Improved JSDocs.
Updated dependencies: @ariakit/react-core@0.4.1

0.4.0

This version introduces enhanced support for CSS animations and transitions, along with a few breaking changes for quite specific cases. The majority of users won't be impacted by these.

Please review the brief notes following the BREAKING labels on each update to determine if any changes are needed in your code.

Improved animation support

BREAKING if you have popups with CSS animation/transition, but aren't using the animated prop.

This version enhances support for CSS animations and transitions on Ariakit components that use Disclosure. This includes Dialog, Popover, Combobox, Select, Hovercard, Menu, and Tooltip.

These components now support enter and leave transitions and animations right out of the box, eliminating the need to provide an explicit animated prop. If an enter animation is detected, the component will automatically wait for a leave animation to complete before unmounting or hiding itself.

This means that if you've set any CSS animation/transition property on a dialog and didn't previously specify the animated prop, you might now notice a delay when closing the dialog. If this isn't what you want, you can turn off the CSS animation/transition using the [data-leave] selector:

.dialog[data-leave] {
  transition: unset;
}
.dialog[data-leave] {
  transition: unset;
}

Use the [data-enter] selector to apply CSS transitions. For CSS animations, use the newly introduced [data-open] selector. The [data-leave] selector can be used for both transitions and animations.

`ComboboxList` is no longer focusable

BREAKING if you're using the ComboboxList component directly with Focusable props.

The ComboboxList component is no longer focusable and doesn't accept focusable props such as autoFocus, disabled, and onFocusVisible anymore. If you need focusable features specifically on the ComboboxList component, you can use composition to render it as a Focusable component.

Before:

<ComboboxList disabled />
<ComboboxList disabled />

After:

<ComboboxList render={<Focusable disabled />} />
<ComboboxList render={<Focusable disabled />} />

Composite widgets with `grid` role

BREAKING if you're manually setting the role="grid" prop on a composite widget.

Ariakit automatically assigns the role prop to all composite items to align with the container role. For example, if SelectPopover has its role set to listbox (which is the default value), its owned SelectItem elements will automatically get their role set to option.

In previous versions, this was also valid for composite widgets with a grid role, where the composite item element would automatically be given role="gridcell". This is no longer the case, and you're now required to manually pass role="gridcell" to the composite item element if you're rendering a container with role="grid".

Before:

<SelectPopover role="grid">
  <SelectRow> {/* Automatically gets role="row" */}
    <SelectItem> {/* Automatically gets role="gridcell" */}
<SelectPopover role="grid">
  <SelectRow> {/* Automatically gets role="row" */}
    <SelectItem> {/* Automatically gets role="gridcell" */}

After:

<SelectPopover role="grid">
  <SelectRow> {/* Still gets role="row" */}
    <SelectItem role="gridcell">
<SelectPopover role="grid">
  <SelectRow> {/* Still gets role="row" */}
    <SelectItem role="gridcell">

This change is due to the possibility of rendering a composite item element with a different role as a child of a static div with role="gridcell", which is a valid and frequently used practice when using the grid role. As a result, you no longer have to manually adjust the role prop on the composite item:

<SelectPopover role="grid">
  <SelectRow>
    <div role="gridcell">
      <SelectItem render={<button />}>
<SelectPopover role="grid">
  <SelectRow>
    <div role="gridcell">
      <SelectItem render={<button />}>

Previously, you had to explicitly pass role="button" to the SelectItem component above, otherwise it would automatically receive role="gridcell", leading to an invalid accessibility tree.

Radio types have improved

BREAKING if you're using TypeScript with the onChange prop on Radio, FormRadio, or MenuItemRadio.

The onChange callback argument type has changed from React.SyntheticEvent to React.ChangeEvent.

Before:

<Radio onChange={(event: React.SyntheticEvent) => {}} />
<Radio onChange={(event: React.SyntheticEvent) => {}} />

After:

<Radio onChange={(event: React.ChangeEvent) => {}} />
<Radio onChange={(event: React.ChangeEvent) => {}} />

Public data attributes have now boolean values

BREAKING if you're depending on data attributes to carry an empty string ("") value.

In previous versions, data attributes such as data-active, data-active-item, data-enter, data-leave, and data-focus-visible would carry an empty string ("") value when active, and undefined when inactive. Now, they have a true value when active, but remain undefined when inactive.

Their use as CSS selectors remains unchanged. You should continue to select them with the attribute selector with no value (e.g., [data-enter]). However, if you're employing them in different ways or have snapshot tests that depend on their value, you might need to update your code.

Removed deprecated features

BREAKING if you haven't addressed the deprecation warnings from previous releases.

This version eliminates features that were deprecated in previous releases: the backdropProps and as props, as well as the ability to use a render function for the children prop across all components.

Before:

<Dialog backdropProps={{ className: "backdrop" }} />
<Combobox as="textarea" />
<Combobox>
  {(props) => <textarea {...props} />}
</Combobox>
<Dialog backdropProps={{ className: "backdrop" }} />
<Combobox as="textarea" />
<Combobox>
  {(props) => <textarea {...props} />}
</Combobox>

After:

<Dialog backdrop={<div className="backdrop" />} />
<Combobox render={<textarea />} />
<Combobox render={(props) => <textarea {...props} />} />
<Dialog backdrop={<div className="backdrop" />} />
<Combobox render={<textarea />} />
<Combobox render={(props) => <textarea {...props} />} />

You can learn more about these new features in the Composition guide.

Other updates

Deprecated MenuBar in favor of Menubar components.
The type prop on Tooltip has been deprecated. See Tooltip anchors must have accessible names.
Removed the ancestors of open, nested modals from the accessibility tree.
Tooltips no longer use aria-describedby to associate the tooltip content with the anchor.
Added new disclosure property to disclosure stores.
Updated dependencies: @ariakit/react-core@0.4.0

0.3.14

Fixed a regression introduced in v0.3.13 where dialogs wouldn't close when clicking outside on iOS.
Updated dependencies: @ariakit/react-core@0.3.14

0.3.13

Improved performance of large collections

Components like MenuItem, ComboboxItem, and SelectItem should now offer improved performance when rendering large collections.

New `FormControl` component

This version introduces a new FormControl component. In future versions, this will replace the FormField component.

Other updates

Adjusted the focus behavior in Safari to occur prior to the pointerup event instead of mouseup.
Improved JSDocs.
Updated dependencies: @ariakit/react-core@0.3.13

0.3.12

The auto-select feature on Combobox now resets with each keystroke.
Fixed Combobox with the autoSelect prop calling onFocus with every input change.
Fixed Hovercard flickering when used with shadow DOM.
Fixed Select with Combobox scroll jumping when opening using keyboard navigation.
Fixed CompositeItem triggering blur on focus.
Fixed ComboboxItem not triggering the onClick event when the item is partially visible.
Improved JSDocs.
Updated dependencies: @ariakit/react-core@0.3.12

0.3.11

Modal Combobox

The Combobox components now support the modal prop on ComboboxPopover.

When a modal combobox is expanded, users can interact with and tab through all the combobox controls, including Combobox, ComboboxDisclosure, and ComboboxCancel, even if they're rendered outside the popover. The rest of the page will be inert.

Controlling the auto-select functionality of Combobox

The Combobox component now includes a new getAutoSelectId prop. This allows you to specify the ComboboxItem that should be auto-selected if the autoSelect prop is true.

By default, the first enabled item is auto-selected. Now you can customize this behavior by returning the id of another item from getAutoSelectId:

<Combobox
  autoSelect
  getAutoSelectId={(items) => {
    // Auto select the first enabled item with a value
    const item = items.find((item) => {
      if (item.disabled) return false;
      if (!item.value) return false;
      return true;
    });
    return item?.id;
  }}
/>
<Combobox
  autoSelect
  getAutoSelectId={(items) => {
    // Auto select the first enabled item with a value
    const item = items.find((item) => {
      if (item.disabled) return false;
      if (!item.value) return false;
      return true;
    });
    return item?.id;
  }}
/>

Styling Combobox without an active descendant

The Combobox component now includes a data-active-item attribute when it's the only active item in the composite widget. In other words, when no ComboboxItem is active and the focus is solely on the combobox input.

You can use this as a CSS selector to style the combobox differently, providing additional affordance to users who pressed ↑ on the first item or ↓ on the last item. This action would place both virtual and actual DOM focus on the combobox input.

.combobox[data-active-item] {
  outline-width: 2px;
}
.combobox[data-active-item] {
  outline-width: 2px;
}

Other updates

Fixed useTabStore return value not updating its own reference.
Fixed keyboard navigation on Combobox when the content element is a grid.
Fixed ComboboxDisclosure to update its aria-expanded attribute when the combobox expands.
Fixed Maximum update depth exceeded warning when rendering multiple collection items on the page.
Improved JSDocs.
Updated dependencies: @ariakit/react-core@0.3.11

0.3.10

Overwriting `aria-selected` value on `ComboboxItem`

It's now possible to pass a custom aria-selected value to the ComboboxItem component, overwriting the internal behavior.

Limiting `slide` on popovers

When components like Popover and Menu with the slide prop are positioned to the right or left of the anchor element, they will now cease to slide across the screen, disengaged from the anchor element, upon reaching the edge of said element.

Other updates

Fixed blurOnHoverEnd set to false not keeping submenus open.
Fixed scroll jump on Safari when selecting a CompositeItem.
Fixed preserveTabOrderAnchor on nested menus.
Fixed focus behavior when using the preserveTabOrder prop.
Updated dependencies: @ariakit/react-core@0.3.10

0.3.9

Automatic role on ComboboxGroup

The ComboboxGroup component now automatically assigns the role attribute as rowgroup if it's nestled within a ComboboxPopover or ComboboxList wrapper that has the role attribute set to grid.

Custom submenu auto focus

When opening nested Menu components with Enter, Space, or arrow keys, the first tabbable element will now receive focus, even if it's not a MenuItem element. This should enable custom popups that behave like submenus, but use different semantics.

Hovercard display timeout

The Hovercard, Menu, and Tooltip components now display synchronously when the timeout or showTimeout states are set to 0. This should stop submenus from vanishing for a few frames prior to displaying a new menu when hovering over menu items in sequence.

Other updates

Fixed CollectionItem elements getting out of order when composing stores.
Fixed MenuButton not assigning the correct role attribute when used within a ComboboxList element.
Fixed MenuItem with an explicit focusOnHover prop not moving focus properly.
Fixed blurOnHoverEnd not working on submenu triggers.
Fixed Dialog not respecting the controlled open state.
Fixed unmounted SelectPopover not re-opening when its open state is initially set to true.
Fixed TypeScript build errors.
Fixed focus order when using Popover with the portal prop with VoiceOver.
Updated dependencies: @ariakit/react-core@0.3.9

0.3.8

Multi-selectable Combobox

We've added support for the Combobox with multiple selection capabilities using a new selectedValue prop, along with defaultSelectedValue and setSelectedValue.

This works similarly to the value prop on Select components. If it receives an array, the combobox will allow multiple selections. By default, it's a string that represents the selected value in a single-select combobox.

Check out the Multi-selectable Combobox example to see it in action.

New Combobox components

This version introduces new Combobox components:

ComboboxLabel: This renders a label element for a Combobox, with the htmlFor prop set automatically.
ComboboxItemCheck: This displays a checkmark for a ComboboxItem when the item is selected.

Other updates

Added resetValueOnSelect state to Combobox components.
Added selectValueOnClick prop to ComboboxItem.
Fixed SelectItem rendering an aria-selected attribute even when the value prop is omitted.
Updated dependencies: @ariakit/react-core@0.3.8

0.3.7

Expanding Menubar

The Menubar component will now only expand if there's another menu already expanded in the same menubar.

Internal data attribute changes

Just like the change in v0.3.6 that removed the data-command and data-disclosure attributes from elements, this update stops the data-composite-hover attribute from infiltrating composite item elements in the DOM. We're mentioning this in the changelog as some users might have snapshot tests that require updating.

Other updates

Fixed setSelectionRange error when used with unsupported⁠ input types.
Fixed MenuButton with showOnHover not updating the activeId state when hovered.
Updated onFocusVisible element type on Focusable from Element to HTMLElement.
Updated dependencies: @ariakit/react-core@0.3.7

0.3.6

Data attributes for duplicate components

The internal logic that identifies duplicate components has been refined. This implies that some internal data-* attributes will no longer seep into the rendered DOM elements. If you're doing snapshot tests on the DOM generated by Ariakit components, you should see the data-command and data-disclosure attributes removed.

Fixed Hovercard when used with multiple HovercardAnchor elements.
Added new preserveTabOrderAnchor prop to Portal and related components.
Added new tabbable prop to CompositeItem and related components.
Added new blurOnHoverEnd prop to CompositeHover and related components.
Updated dependencies: @ariakit/react-core@0.3.6

Previous versions⁠

Changelog

Stay tuned