# What changed in @headlessui/react

> 59 changes in @headlessui/react 2 from its official release notes, upgrade guides and advisories: 12 breaking, 4 deprecations, 29 new APIs and options. Each one cited. Sources checked 2026-10-26. HTML: https://unstale.sh/npm/@headlessui/react/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @headlessui/react 2

### Breaking changes

- The default tag for ComboboxOption has changed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The default tag for ComboboxOptions has changed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Dialog is focused by default instead of focusing the first focusable element. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The deprecated DialogBackdrop component has been removed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The deprecated DialogOverlay component has been removed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Checkbox, Switch, and RadioGroup always render hidden form input fields. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Pressing enter on ListboxButton now attempts form submission. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The default tag for ListboxOption has changed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The default tag for ListboxOptions has changed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- React 18 is now required. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The default tag for TabGroup has changed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Transition components now default to Fragment instead of div. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)

### Deprecations

- The active prop is deprecated in favor of the focus prop. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Dot notation for components is deprecated. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The entered prop on Transition is deprecated. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- RadioGroup.Option is deprecated in favor of the new Radio component. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)

### New APIs and options

- A new prop is available on Combobox, Listbox, Menu, and Popover. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Focusable components now accept an autoFocus prop. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new Button component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A CSS variable is available on ListboxOptions, MenuItems, and PopoverPanel. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A CSS variable is available on the ComboboxOptions component. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new Checkbox component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new CloseButton component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- ComboboxOptions now has a frozen value. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- New data attributes provide an alternative to the existing data-headlessui-state attribute. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new DataInteractive component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new Description component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new Field component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new Fieldset component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The Combobox can immediately open when its input receives focus. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new Input component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A CSS variable is available on the ComboboxOptions component. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new Label component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new Legend component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new ListboxSelectedOption component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new MenuHeading component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new MenuSection component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new MenuSeparator component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new prop is available on Combobox, Listbox, Menu, and Popover. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The Combobox component now accepts an onClose prop. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new prop is available on Combobox, Listbox, Menu, and Popover. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new Select component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new Textarea component is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- A new useClose hook is available. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The Combobox component now accepts a virtual prop. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)

### Behavior and default changes

- Combobox now allows a null value. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)

### Fixes and other changes

- Fixes an error when passing props on Fragment caused by Symbol(react.lazy). (2.2.10) — [release notes](https://github.com/tailwindlabs/headlessui/blob/d13526d02a2de92c4ad7b62c15cd980636543fe2/packages/@headlessui-react/CHANGELOG.md#2210---2026-04-07)
- A Portal is no longer rendered while hydrating. (2.2.10) — [release notes](https://github.com/tailwindlabs/headlessui/blob/d13526d02a2de92c4ad7b62c15cd980636543fe2/packages/@headlessui-react/CHANGELOG.md#2210---2026-04-07)
- Event cancellation is fixed when using disabled or aria-disabled attributes. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Focus handling in ComboboxInput is fixed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Horizontal scrolling inside Dialog is fixed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Event cancellation is fixed when using disabled or aria-disabled attributes. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- The displayValue callback in ComboboxInput no longer executes unnecessarily. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Focus handling in ListboxOptions is fixed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Focus handling in MenuItems is fixed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Types for the multiple prop in Combobox are fixed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Scroll-locking on iOS is fixed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- touchmove is no longer canceled on input elements inside a dialog. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)
- Enter transitions in Transition are fixed. (2.0.0) — [release notes](https://github.com/tailwindlabs/headlessui/blob/HEAD/packages/@headlessui-react/CHANGELOG.md)