unstale

npm / @headlessui/react

@headlessui/react

What changed in @headlessui/react 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-26.

12 breaking4 deprecations29 new APIs and options1 behavior and defaults13 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.2.7 on npm

@headlessui/react 259 changes

Breaking changes 12

  • The default tag for ComboboxOption has changed.

    2.0.0release notes

  • The default tag for ComboboxOptions has changed.

    2.0.0release notes

  • Dialog is focused by default instead of focusing the first focusable element.

    2.0.0release notes

  • The deprecated DialogBackdrop component has been removed.

    2.0.0release notes

  • The deprecated DialogOverlay component has been removed.

    2.0.0release notes

  • Checkbox, Switch, and RadioGroup always render hidden form input fields.

    2.0.0release notes

  • Pressing enter on ListboxButton now attempts form submission.

    2.0.0release notes

  • The default tag for ListboxOption has changed.

    2.0.0release notes

  • The default tag for ListboxOptions has changed.

    2.0.0release notes

  • React 18 is now required.

    2.0.0release notes

  • The default tag for TabGroup has changed.

    2.0.0release notes

  • Transition components now default to Fragment instead of div.

    2.0.0release notes

Deprecations 4

  • The active prop is deprecated in favor of the focus prop.

    2.0.0release notes

  • Dot notation for components is deprecated.

    2.0.0release notes

  • The entered prop on Transition is deprecated.

    2.0.0release notes

  • RadioGroup.Option is deprecated in favor of the new Radio component.

    2.0.0release notes

New APIs and options 29

  • A new prop is available on Combobox, Listbox, Menu, and Popover.

    2.0.0release notes

  • Focusable components now accept an autoFocus prop.

    2.0.0release notes

  • A new Button component is available.

    2.0.0release notes

  • A CSS variable is available on ListboxOptions, MenuItems, and PopoverPanel.

    2.0.0release notes

  • A CSS variable is available on the ComboboxOptions component.

    2.0.0release notes

  • A new Checkbox component is available.

    2.0.0release notes

  • A new CloseButton component is available.

    2.0.0release notes

  • ComboboxOptions now has a frozen value.

    2.0.0release notes

  • New data attributes provide an alternative to the existing data-headlessui-state attribute.

    2.0.0release notes

  • A new DataInteractive component is available.

    2.0.0release notes

  • A new Description component is available.

    2.0.0release notes

  • A new Field component is available.

    2.0.0release notes

  • A new Fieldset component is available.

    2.0.0release notes

  • The Combobox can immediately open when its input receives focus.

    2.0.0release notes

  • A new Input component is available.

    2.0.0release notes

  • A CSS variable is available on the ComboboxOptions component.

    2.0.0release notes

  • A new Label component is available.

    2.0.0release notes

  • A new Legend component is available.

    2.0.0release notes

  • A new ListboxSelectedOption component is available.

    2.0.0release notes

  • A new MenuHeading component is available.

    2.0.0release notes

  • A new MenuSection component is available.

    2.0.0release notes

  • A new MenuSeparator component is available.

    2.0.0release notes

  • A new prop is available on Combobox, Listbox, Menu, and Popover.

    2.0.0release notes

  • The Combobox component now accepts an onClose prop.

    2.0.0release notes

  • A new prop is available on Combobox, Listbox, Menu, and Popover.

    2.0.0release notes

  • A new Select component is available.

    2.0.0release notes

  • A new Textarea component is available.

    2.0.0release notes

  • A new useClose hook is available.

    2.0.0release notes

  • The Combobox component now accepts a virtual prop.

    2.0.0release notes

Behavior and default changes 1

Fixes and other changes 13

  • Fixes an error when passing props on Fragment caused by Symbol(react.lazy).

    2.2.10release notes

  • A Portal is no longer rendered while hydrating.

    2.2.10release notes

  • Event cancellation is fixed when using disabled or aria-disabled attributes.

    2.0.0release notes

  • Focus handling in ComboboxInput is fixed.

    2.0.0release notes

  • Horizontal scrolling inside Dialog is fixed.

    2.0.0release notes

  • Event cancellation is fixed when using disabled or aria-disabled attributes.

    2.0.0release notes

  • The displayValue callback in ComboboxInput no longer executes unnecessarily.

    2.0.0release notes

  • Focus handling in ListboxOptions is fixed.

    2.0.0release notes

  • Focus handling in MenuItems is fixed.

    2.0.0release notes

  • Types for the multiple prop in Combobox are fixed.

    2.0.0release notes

  • Scroll-locking on iOS is fixed.

    2.0.0release notes

  • touchmove is no longer canceled on input elements inside a dialog.

    2.0.0release notes

  • Enter transitions in Transition are fixed.

    2.0.0release notes