ariakit

New autoSelect mode

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

<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/[email protected]

• Updated dependencies: @ariakit/[email protected]

New autoSelect mode

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

<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/[email protected]

• Added disclosure property to disclosure stores.
• Improved JSDocs.

• Queries no longer match inert elements.
• Updated dependencies: @ariakit/[email protected]

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

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.

Use the [data-enter] selector for 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 />

After:

<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" */}

After:

<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 />}>

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 and 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) => {}} />

After:

<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>

After:

<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.
• Revamped utilities for creating Ariakit components.
• The type prop for the 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/[email protected]

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

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.

Use the [data-enter] selector for 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 />

After:

<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" */}

After:

<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 />}>

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 and 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) => {}} />

After:

<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>

After:

<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 for the 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/[email protected]

Improved animation support

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.

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

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" */}

After:

<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 />}>

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.

Other updates

• Added removeUndefinedValues utility function.
• Added new disclosure property to disclosure stores.

• Fixed a regression introduced in v0.3.13 where dialogs wouldn't close when clicking outside on iOS.

• Fixed a regression introduced in v0.3.13 where dialogs wouldn't close when clicking outside on iOS.
• Updated dependencies: @ariakit/[email protected]

• Updated dependencies: @ariakit/[email protected]

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/[email protected]

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/[email protected]

Improved performance of large collections

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

Other updates

• Improved JSDocs.

• Added missing properties to dispatched events.
• Updated dependencies: @ariakit/[email protected]

• 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/[email protected]

• 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/[email protected]

• Fixed CompositeItem triggering blur on focus.
• Improved JSDocs.

Home and End keys on text fields

Pressing the Home or End keys on text fields will now move the cursor (selectionStart/selectionEnd properties) to the start or finish of the text when using the press function.

Other updates

• Updated dependencies: @ariakit/[email protected]

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;
  }}
/>

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;
}

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/[email protected]