PackageTrack

npm · #4495

@headlessui/react

2.2.10tailwindlabs/headlessui ↗

A set of completely unstyled, fully accessible UI components for React, designed to integrate beautifully with Tailwind CSS.

Release timeline

819 releases since 2020
202120222023202420252026

Releases

  1. 2.2.107 Apr 2026
    Release notes2 sources agree

    Fixed

    • Don’t render <Portal> while hydrating (#3825)
    • Fix passing props on Fragment error due to Symbol(react.lazy) (#3873)
    Open source →
  2. 2.2.925 Sept 2025
    Release notes2 sources agree

    Fixed

    • Improve focus management in shadow DOM roots (#3794)
    • Don't accidentally open the Combobox when touching the ComboboxButton while dragging on mobile (#3795)
    • Ensure sibling Dialog components are scrollable on mobile (#3796)
    • Infer Combobox type based on onChange handler (#3798)
    • Allow home/end key default behavior inside ComboboxInput when Combobox is closed (#3798)
    • Ensure interacting with a Dialog on iOS works after interacting with a disallowed area (#3801)
    • Freeze Listbox values as soon as a value is selected (#3802)
    • Ensure refs are forwarded when freezing data (#3390)
    • Do not serialize React components into form fields (49e9e8e)
    Open source →
  3. 2.2.812 Sept 2025
    Release notes2 sources agree

    Fixed

    • Ensure we are not freezing data when the static prop is used (#3779)
    • Ensure onChange types are contravariant instead of bivariant (#3781)
    • Support <summary> as a focusable element inside <details> (#3389)
    • Fix Maximum update depth exceeded crash when using transition prop (#3782)
    • Ensure pressing Tab in the ComboboxInput, correctly syncs the input value (#3785)
    • Ensure --button-width and --input-width have the latest value (#3786)
    • Fix 'Invalid prop data-headlessui-state supplied to React.Fragment' warning (#3788)
    • Ensure element in ref callback is always connected when rendering in a Portal (#3789)
    • Ensure form state is up to date when using uncontrolled components (#3790)
    • Ensure data-open on ComboboxInput is up to date (#3791)
    • Ensure changing the immediate prop value on the Combobox component works as expected (#3792)
    Open source →
  4. 2.2.730 Jul 2025
    Release notes2 sources agree

    Fixed

    • Fix incorrect double invocation of menu items, listbox options and combobox options (#3766)
    • Fix memory leak in SSR environment (#3767)
    • Ensure programmatic .click() on MenuButton ref works (#3768)
    • Don't activate hovered items while using the keyboard (#3769)
    Open source →
  5. 2.2.624 Jul 2025
    Release notes2 sources agree

    Fixed

    • Fix immediately closing Listbox by requiring some cursor movement (#3762)
    Open source →
  6. 2.2.523 Jul 2025
    Release notes2 sources agree

    Fixed

    • Fix listbox closing immediately after opening on touch devices (#3755)
    Open source →
  7. 2.2.420 May 2025
    Release notes2 sources agree

    Fixed

    • Fix Combobox error (unexpected undefined) when using virtual mode (#3734)
    Open source →
  8. 2.2.312 May 2025
    Release notes2 sources agree

    Added

    • Add a quick trigger action to the Menu, Listbox and Combobox components (#3700)

    Fixed

    • Fix clicking Label component should open <Input type="file"> (#3707)
    • Ensure clicking on interactive elements inside Label component works (#3709)
    • Fix focus not returned to SVG Element (#3704)
    • Fix Listbox not focusing first or last option on ArrowUp / ArrowDown (#3721)
    • Performance improvement: only re-render top-level component when nesting components e.g.: Menu inside a Dialog (#3722)
    • Fix closing Menu when other Menu is opened (#3726)
    Open source →
  9. 2.2.217 Apr 2025
    Release notes

    Fixed

    • Improve Menu component performance (#3685)
    • Improve Listbox component performance (#3688)
    • Improve Combobox component performance (#3697)
    • Open Menu and Listbox on mousedown (#3689)
    • Fix Transition component from incorrectly exposing the Closing state (#3696)
    Open source →
    Additional notes

    Fixed

    • Improve Menu component performance (#3685)
    • Improve Listbox component performance (#3688)
    • Open Menu and Listbox on mousedown (#3689)
    • Fix Transition component from incorrectly exposing the Closing state (#3696)
    • Improve Combobox component performance (#3697)
    Open source →
  10. 2.2.14 Apr 2025
    Release notes2 sources agree

    Added

    • Accept tabIndex on the Checkbox component (#3645)
    • Accept tabIndex on the RadioGroup component (#3646)

    Fixed

    • Use correct ownerDocument when using internal Portal component (#3594)
    • Bump @tanstack/react-virtual to fix warnings in React 19 projects (#3588)
    • Fix aria-invalid attributes to have a valid 'true' value (#3639)
    • Add missing invalid prop to Combobox component (#3677)
    • Fix Unexpected undefined crash in Combobox component with virtual mode (#3678)
    Open source →
  11. 2.2.025 Oct 2024
    Release notes2 sources agree

    Added

    • Add React 19 support (#3543)
    Open source →
  12. 2.1.1010 Oct 2024
    Release notes2 sources agree

    Fixed

    • Use React.JSX instead of deprecated global JSX (#3511)
    • Fix crash in ListboxOptions when using as={Fragment} (#3513)
    Open source →
  13. 2.1.93 Oct 2024
    Release notes2 sources agree

    Fixed

    • Ensure Element is available before polyfilling to prevent crashes in non-browser environments (#3493)
    • Fix crash when using instanceof HTMLElement in some environments (#3494)
    • Cleanup process in Combobox component when using virtualization (#3495)
    Open source →
  14. 2.1.812 Sept 2024
    Release notes2 sources agree

    Fixed

    • Fix crash when using as={Fragment} on MenuButton, ListboxButton, DisclosureButton or Button components (#3478)
    Open source →
  15. 2.1.711 Sept 2024
    Release notes2 sources agree

    Fixed

    • Prevent crash in environments where Element.prototype.getAnimations is not available (#3473)
    Open source →
  16. 2.1.69 Sept 2024
    Release notes2 sources agree

    Fixed

    • Fix ListboxOptions being incorrectly marked as inert (#3466)
    • Fix crash when using DisclosureButton inside of a DisclosurePanel when the Disclosure is open by default (#3465)
    Open source →
  17. 2.1.54 Sept 2024
    Release notes2 sources agree

    Fixed

    • Fix transition bug on Firefox, triggered by clicking the PopoverButton in rapid succession (#3452)
    Open source →
  18. 2.1.43 Sept 2024
    Release notes2 sources agree

    Fixed

    • Fix components not closing properly when using the transition prop (#3448)
    Open source →
  19. 2.1.323 Aug 2024
    Release notes2 sources agree

    Fixed

    • Ensure Transition component state doesn't change when it becomes hidden (#3372)
    • Fix closing components using the transition prop, and after scrolling the page (#3407)
    • Ensure all client components are marked correctly to avoid a crash with React 19 and Turbopack (#3429)
    Open source →
  20. 2.1.25 Jul 2024
    Release notes2 sources agree

    Fixed

    • Fix prematurely added anchoring styles on ListboxOptions (#3337)
    • Ensure unmount on Dialog works in combination with the transition prop on DialogBackdrop and DialogPanel components (#3352)
    • Fix crash in Combobox component when in virtual mode when options are empty (#3356)
    • Fix hanging tests when using anchor prop (#3357)
    • Fix transition and focus prop combination for PopoverPanel component (#3361)
    • Fix outside click in nested portalled Popover components (#3362)
    • Fix restoring focus to correct element when closing Dialog component (#3365)
    • Fix flushSync warning for Combobox component with immediate prop enabled (#3366)
    Open source →
  21. 2.1.126 Jun 2024
    Release notes2 sources agree

    Fixed

    • Fix issues spreading omitted props onto components (#3313)
    • Fix initial anchor="selection" positioning (#3324)
    • Fix render prop in ComboboxOptions to use any instead of unknown (#3327)
    • Fix incorrect Transition boundary for Dialog component (#3331)
    Open source →
  22. 2.1.021 Jun 2024
    Release notes

    We just released Headless UI v2.1 for React, which dramatically simplifies our transition APIs and adds support for rendering multiple dialogs as siblings. See our announcement blog to learn more.

    Changelog

    Added

    • Add ability to render multiple Dialog components at once (without nesting them) (#3242)
    • Add new data-attribute-based transition API (#3273, #3285, #3307, #3309, #3312)
    • Add DialogBackdrop component (#3307, #3310)
    • Add PopoverBackdrop component to replace PopoverOverlay (#3308)

    Fixed

    • Keep Combobox open when clicking scrollbar in ComboboxOptions (#3249)
    • Ensure ComboboxInput does not sync with current value while typing (#3259)
    • Fix visual jitter in Combobox component when using native scrollbar (#3190)
    • Improve UX by freezing ComboboxOptions while closing (#3304)
    • Merge incoming style prop on ComboboxOptions, ListboxOptions, MenuItems, and PopoverPanel components (#3250)
    • Prevent focus on Checkbox when it is disabled (#3251)
    • Use useId instead of React internals (for React 19 compatibility) (#3254)
    • Cancel outside click behavior on touch devices when scrolling (#3266)
    • Correctly apply conditional classes when using Transition and TransitionChild components (#3303)

    Changed

    • Allow using the Tab and Shift+Tab keys when the Listbox component is open (#3284)
    Open source →
    Additional notes

    Added

    • Add ability to render multiple Dialog components at once (without nesting them) (#3242)
    • Add new data-attribute-based transition API (#3273, #3285, #3307, #3309, #3312)
    • Add DialogBackdrop component (#3307, #3310)
    • Add PopoverBackdrop component to replace PopoverOverlay (#3308)

    Fixed

    • Keep Combobox open when clicking scrollbar in ComboboxOptions (#3249)
    • Ensure ComboboxInput does not sync with current value while typing (#3259)
    • Fix visual jitter in Combobox component when using native scrollbar (#3190)
    • Improve UX by freezing ComboboxOptions while closing (#3304)
    • Merge incoming style prop on ComboboxOptions, ListboxOptions, MenuItems, and PopoverPanel components (#3250)
    • Prevent focus on Checkbox when it is disabled (#3251)
    • Use useId instead of React internals (for React 19 compatibility) (#3254)
    • Cancel outside click behavior on touch devices when scrolling (#3266)
    • Correctly apply conditional classes when using Transition and TransitionChild components (#3303)

    Changed

    • Allow using the Tab and Shift+Tab keys when the Listbox component is open (#3284)
    Open source →
  23. 2.0.424 May 2024
    Release notes2 sources agree

    Fixed

    • [internal] Don’t set a focus fallback for Dialog’s in demo mode (#3194)
    • Ensure page doesn't scroll down when pressing Escape to close the Dialog component (#3218)
    • Fix crash when toggling between virtual and non-virtual mode in Combobox component (#3236)
    • Ensure tabbing to a portalled PopoverPanel component moves focus inside (without using PortalGroup) (#3239)
    • Only handle form reset when defaultValue is used (#3240)

    Deprecated

    • Mark SwitchGroup as deprecated, prefer Field instead (#3232)

    Changed

    • Use native fieldset instead of div by default for Fieldset component (#3237)
    Open source →
  24. 2.0.37 May 2024
    Release notes2 sources agree

    Fixed

    • Make sure disabling demo mode on Combobox works (#3182)
    Open source →
  25. 2.0.27 May 2024
    Release notes2 sources agree

    Fixed

    • Improve performance of internal useInertOthers hook (#3181)
    Open source →
  26. 2.0.16 May 2024
    Release notes2 sources agree

    Fixed

    • Remove accidental deprecation comments on DialogPanel and DialogTitle (#3176)
    Open source →
  27. 2.0.06 May 2024
    Release notes

    We just released Headless UI v2.0 for React which includes a ton of new stuff:

    • Built-in anchor positioning — using Floating UI, components like Menu, Listbox, and more can now automatically position their popovers to be anchored to their trigger, adapting as needed to changes in the viewport.
    • Headless checkbox component — we've added a headless Checkbox component to complement our existing RadioGroup component, making it easy to build totally custom checkbox controls.
    • HTML form components — we've added Input, Select, Textarea, Label, Description, Fieldset, and Legend components that handle all of the ID generation and aria-* attribute mapping you need to do to connect form fields together.
    • Improved hover and focus-visible detection — using hooks from the awesome React Aria library under the hood, Headless UI now adds smarter data-hover and data-focus attributes to your controls that behave more consistently across different devices than the native pseudo-classes.
    • Combobox list virtualization — the Combobox component can now handle giant lists of options with no performance issues.

    Changelog

    Added

    • Add new Checkbox component (#2887, #2962)
    • Add new Button component (#2887)
    • Add new Input component (#2887, #2902, #2940)
    • Add new Textarea component (#2887, #2902, #2940)
    • Add new Select component (#2887, #2902)
    • Add new Fieldset and Legend components (#2887)
    • Add new Field, Label, Description components (#2887, #2941)
    • Add new MenuSection, MenuHeading, and MenuSeparator components (#2887)
    • Add new ListboxSelectedOption component (#2887)
    • Add new DataInteractive component (#2887)
    • Add new CloseButton component and useClose hook (#3096)
    • Add new anchor, modal, and portal props to Combobox, Listbox, Menu and Popover components (#2887, #3075, #3097, #3111, #3115, #3121, #3124, #3133, #3138, #3148, #3152, #3154, #3157)
    • Add new autoFocus prop to focusable components (#2887)
    • Add new virtual prop to Combobox component (#2779, #3128, #3160, #3161, #3163)
    • Add new onClose prop to Combobox component (#3122)
    • Add new immediate prop to Combobox for immediately opening the Combobox when the input receives focus (#2686)
    • Add new --button-width CSS variable on the ListboxOptions, MenuItems, and PopoverPanel components (#2887, #3058)
    • Add new --input-width and --button-width CSS variables on the ComboboxOptions component (#3057)
    • Add new data-* attributes as an alternative to the existing data-headlessui-state attribute (#2887, #3035, #3061)

    Fixed

    • Fix scroll-locking on iOS (#2891)
    • Fix cancellation of events when using disabled or aria-disabled attributes (#2890)
    • Fix unnecessary execution of the displayValue callback in ComboboxInput component (#3048)
    • Fix types for multiple prop in Combobox component (#3099)
    • Fix focus handling in ComboboxInput component (#3065, #3073)
    • Fix enter transitions in Transition component (#3074)
    • Fix focus handling in ListboxOptions and MenuItems components (#3112)
    • Fix horizontal scrolling inside the Dialog component (#2889)

    Changed

    • Require React 18 (#2887, #3092, #3131)
    • Always render hidden form input fields for Checkbox, Switch and RadioGroup components (#3095)
    • Deprecate the RadioGroup.Option component in favor of new Radio component (#2887)
    • Deprecate the active prop in favor of new focus prop (#2887)
    • Dialog is now focused by default instead of the first focusable element (#2887)
    • Change default tags for ListboxOptions, ListboxOption, ComboboxOptions, ComboboxOption, and TabGroup components (#3109)
    • Change default tag from div to Fragment on Transition components (#3110, #3147)
    • Allow Combobox component to have null value (#3064, #3100)
    • Attempt form submission when pressing enter on the ListboxButton component (#2972)
    • Deprecate the entered prop on the Transition component (#3089)
    • Add frozen value to ComboboxOptions component (#3126)

    <h2 id="upgrading-from-v1">Upgrading from v1</h2>

    Update dependencies

    Install the latest version of the package via npm:

    npm install @headlessui/react@latest

    Default element changes

    The default rendered element has changed for a number of components in v2.0:

    Component v1.x element v2.0 element
    Transition div Fragment
    TransitionChild div Fragment
    ListboxOptions ul div
    ListboxOption li div
    ComboboxOptions ul div
    ComboboxOption li div
    TabGroup Fragment div

    If you are using any of these components without the as prop, you'll need to add the as prop and render the component with the element you need:

    - <Transition ...>
+ <Transition as="div" ...>

    Comboboxes now always support empty values

    Previously the Combobox component required an option to always be set, and you could opt out of this behavior using the nullable prop. In v2.0 comboboxes support empty values by default so you can remove this prop:

    - <Combobox value={selected} onChange={setSelected} nullable>
+ <Combobox value={selected} onChange={setSelected}>

    If you'd like to keep the previous behavior, update your onChange callback to only set the selected value if an option has actually been selected:

     <Combobox
   value={selected}
-  onChange={setSelected}
+  onChange={(newValue) => setSelected((oldValue) => newValue ?? oldValue)}
   onClose={() => setQuery('')}
 >

    Dialogs no longer require a focusable child

    Previously the Dialog component would automatically focus the first focusable child on open. This meant that you had to have at least one focusable element within your dialog, otherwise you would see a warning in your console.

    In v2.0 that is no longer the case and the dialog's root element is focused instead on open.

    If you'd like a child element to receive focus when your dialog is opened, you can add the autoFocus prop to any Headless UI form control:

     <Dialog>
   <DialogPanel>
-    <Listbox ... />
+    <Listbox autoFocus ... />
   </DialogPanel>
 </Dialog>

    For non-Headless UI components, you can add the data-autofocus attribute to any focusable element:

     <Dialog>
   <DialogPanel>
-    <button>...</button>
+    <button data-autofocus>...</button>
   </DialogPanel>
 </Dialog>

    Dropdown components are now modal by default

    The Menu, Combobox, and Listbox dropdowns are now rendered modal by default. When the dropdown is open the page is scroll-locked and all other page content is made inert.

    While this is generally recommended behavior for these components, you can disable this using the modal prop:

    - <ComboboxOptions ...>
+ <ComboboxOptions modal={false} ...>

    Dialog.Overlay and Dialog.Backdrop components removed

    In Headless UI v1.6 we deprecated the Dialog.Overlay and Dialog.Backdrop components. These have now been removed in v2.0.

    If you're using either of these components, you can update your app to use the new DialogPanel approach:

      <Dialog>
-    <Dialog.Overlay className="..." />
+    <div className="..." />
+    <DialogPanel>
       {/* ... */}
+    </DialogPanel>
   </Dialog>

    Deprecated component dot-notation

    The previous component dot-notation has been deprecated in favor of using explicit imports for each individual component. This is to improve compatibility with RSC (React Server Components) and tree-shaking.

    We recommend updating to this new API:

    - import { Menu } from '@headlessui/react'
+ import { Menu, MenuButton, MenuItems, MenuItem } from '@headlessui/react'

  function Example() {
    return (
      <Menu>
-       <Menu.Button>My account</Menu.Button>
-       <Menu.Items>
-         <Menu.Item><a href="/settings">Settings</a></Menu.Item>
-         <Menu.Item><a href="/support">Support</a></Menu.Item>
-         <Menu.Item><a href="/license">License</a></Menu.Item>
-       </Menu.Items>
+       <MenuButton>My account</MenuButton>
+       <MenuItems>
+         <MenuItem><a href="/settings">Settings</a></MenuItem>
+         <MenuItem><a href="/support">Support</a></MenuItem>
+         <MenuItem><a href="/license">License</a></MenuItem>
+       </MenuItems>
      </Menu>
    )
  }

    Deprecated component-specific label and description components

    With the addition of the multi-purpose Field, Label and Description components in v2, we've deprecated the component-specific versions.

    v1.x component v2.0 replacement
    Combobox.Label Label
    Dialog.Description Description
    Listbox.Label Label
    RadioGroup.Description Description
    RadioGroup.Label Label
    Switch.Description Description
    Switch.Group Field
    Switch.Label Label

    We recommend updating to these new components:

    - import { Combobox } from '@headlessui/react'
+ import { Combobox, ComboboxInput, ComboboxOptions, Field, Label } from '@headlessui/react'

  function Example() {
    return (
-     <Combobox>
-       <Combobox.Label>Assignee:</Combobox.Label>
-       <Combobox.Input />
-       <Combobox.Options>{/* ... */}</Combobox.Options>
-     </Combobox>
+     <Field>
+       <Label>Assignee:</Label>
+       <Combobox>
+         <ComboboxInput />
+         <ComboboxOptions>{/* ... */}</ComboboxOptions>
+       </Combobox>
+     <Field>
    )
  }

    Deprecated RadioGroup.Option component

    We've deprecated the RadioGroup.Option in favor of the more terse Radio component.

    We recommend updating to this new component:

      <RadioGroup>
-   <RadioGroup.Option>{*/ ...*/}</RadioGroup.Option>
+   <Radio>{*/ ...*/}</Radio>
  </RadioGroup>

    We've also changed the default tag from div to span.

    Deprecated active prop in favor of focus

    We've deprecated the active prop in favor of the new focus prop on the ComboboxOption, ListboxOption, ListboxOption, MenuItem, MenuItem, RadioOption, and RadioOption components.

    We recommend updating to this new prop:

      <MenuItem >
-   {({ active }) => (
+   {({ focus }) => (
      {/* ... */}    
    )}
  </MenuItem>

    Deprecated @headlessui/tailwindcss package

    With the availability of the new data-* attributes in v2.0, we've deprecated the @headlessui/tailwindcss package.

    We recommend updating to use the new data-* attributes instead. Start by removing this package:

    npm remove @headlessui/tailwindcss

    Next, replace the ui-* class modifiers with data-[*] modifiers:

      <MenuItem
    as="a"
    href="#"
-   className="ui-active:bg-blue-500 ui-active:text-white"
+   className="data-[active]:bg-blue-500 data-[active]:text-white"
  >
    {*/ ...*/}
  </MenuItem>
    Open source →
    Additional notes

    Added

    • Add new Checkbox component (#2887, #2962)
    • Add new Button component (#2887)
    • Add new Input component (#2887, #2902, #2940)
    • Add new Textarea component (#2887, #2902, #2940)
    • Add new Select component (#2887, #2902)
    • Add new Fieldset and Legend components (#2887)
    • Add new Field, Label, and Description components (#2887, #2941)
    • Add new MenuSection, MenuHeading, and MenuSeparator components (#2887)
    • Add new ListboxSelectedOption component (#2887)
    • Add new DataInteractive component (#2887)
    • Add new CloseButton component and useClose hook (#3096)
    • Add new anchor, modal, and portal props to Combobox, Listbox, Menu and Popover components (#2887, #3075, #3097, #3111, #3115, #3121, #3124, #3133, #3138, #3148, #3152, #3154, #3157)
    • Add new autoFocus prop to focusable components (#2887)
    • Add new virtual prop to Combobox component (#2779, #3128, #3160, #3161, #3163)
    • Add new onClose prop to Combobox component (#3122)
    • Add new immediate prop to Combobox for immediately opening the Combobox when the input receives focus (#2686)
    • Add new --button-width CSS variable on the ListboxOptions, MenuItems, and PopoverPanel components (#2887, #3058)
    • Add new --input-width and --button-width CSS variables on the ComboboxOptions component (#3057)
    • Add new data-* attributes as an alternative to the existing data-headlessui-state attribute (#2887, #3035, #3061)

    Fixed

    • Fix scroll-locking on iOS (#2891)
    • Fix cancellation of events when using disabled or aria-disabled attributes (#2890)
    • Fix unnecessary execution of the displayValue callback in ComboboxInput component (#3048)
    • Fix types for multiple prop in Combobox component (#3099)
    • Fix focus handling in ComboboxInput component (#3065, #3073)
    • Fix enter transitions in Transition component (#3074)
    • Fix focus handling in ListboxOptions and MenuItems components (#3112)
    • Fix horizontal scrolling inside the Dialog component (#2889)
    • Don’t cancel touchmove on input elements inside a dialog (#3166)

    Changed

    • Require React 18 (#2887, #3092, #3131)
    • Always render hidden form input fields for Checkbox, Switch, and RadioGroup components (#3095)
    • Deprecate the RadioGroup.Option component in favor of new Radio component (#2887)
    • Deprecate the active prop in favor of new focus prop (#2887)
    • Dialog is now focused by default instead of the first focusable element (#2887)
    • Change default tags for ListboxOptions, ListboxOption, ComboboxOptions, ComboboxOption, and TabGroup components (#3109)
    • Change default tag from div to Fragment on Transition components (#3110, #3147)
    • Allow Combobox component to have a null value (#3064, #3100)
    • Attempt form submission when pressing enter on the ListboxButton component (#2972)
    • Deprecate the entered prop on the Transition component (#3089)
    • Deprecate dot notation for components (#2887, #3170)
    • Add frozen value to ComboboxOptions component (#3126)
    • Remove deprecated DialogBackdrop and DialogOverlay components (#3171)
    Open source →
  28. 2.0.0-alpha.43 Jan 2024pre-release
    Release notes2 sources agree

    Fixed

    • Ensure Input, Select and Textarea expose Ref related types (#2902)
    Open source →
  29. 2.0.0-alpha.321 Dec 2023pre-release
    Release notes2 sources agree

    Fixed

    • Further fine tune scroll locking on iOS (#2891)
    Open source →
  30. 2.0.0-alpha.220 Dec 2023pre-release
    Release notes2 sources agree

    Fixed

    • Allow horizontal scrolling inside the Dialog component (#2889)
    • Improve cancellation of events when using disabled or aria-disabled attributes (#2890)
    Open source →
  31. 2.0.0-alpha.120 Dec 2023pre-release
    Release notes

    Added

    • Add immediate prop to <Combobox /> for immediately opening the Combobox when the input receives focus (#2686)
    • Add virtual prop to Combobox component (#2779)
    • Add new Checkbox component
    • Add new Radio component as an alternative to the existing RadioGroup.Option component
    • Add new Button component
    • Add new Input component
    • Add new Textarea component
    • Add new Select component
    • Add new Field, Label, Description, Fieldset and Legend components
    • Add new DataInteractive component
    • Add new anchor and modal prop to ComboboxOptions, ListboxOptions, MenuItems and PopoverPanel components
    • Add new ListboxSelectedOption component
    • Add new MenuSection, MenuHeading, and MenuSeparator components
    • Add new simplified data-* attributes as an alternative to the existing data-headlessui-state="..." attribute
    • Add autoFocus prop on focusable components (which maps to data-autofocus)

    Changed

    • Bumped to React and React DOM 18
    • Dialog is focused by default instead of the first focusable element (unless an element exists with a data-autofocus in the dialog)

    Fixed

    • Don't call <Dialog>'s onClose twice on mobile devices (#2690)
    • Lazily resolve default containers in <Dialog> (#2697)
    • Ensure hidden Tab.Panel components are hidden from the accessibility tree (#2708)
    • Add support for role="alertdialog" to <Dialog> component (#2709)
    • Ensure blurring the Combobox.Input component closes the Combobox (#2712)
    • Allow changes to the className prop when the <Transition /> component is currently not transitioning (#2722)
    • Export (internal-only) component interfaces for TypeScript compiler (#2313)
    • Fix infinite render-loop for <Disclosure.Panel> and <Popover.Panel> when as={Fragment} (#2760)
    • Fix VoiceOver bug for Listbox component in Chrome (#2824)
    • Fix outside click detection when component is mounted in the Shadow DOM (#2866)
    • Fix CJS types (#2880)
    • Fix error when transition classes contain new lines (#2871)
    • Fix iOS scroll lock glitches
    Open source →
    Additional notes

    Added

    • Add immediate prop to Combobox for immediately opening the Combobox when the input receives focus (#2686)
    • Add virtual prop to Combobox component (#2779)
    • Add new Checkbox component
    • Add new Radio component as an alternative to the existing RadioGroup.Option component
    • Add new Button component
    • Add new Input component
    • Add new Textarea component
    • Add new Select component
    • Add new Field, Label, Description, Fieldset and Legend components
    • Add new DataInteractive component
    • Add new anchor and modal prop to ComboboxOptions, ListboxOptions, MenuItems and PopoverPanel components
    • Add new ListboxSelectedOption component
    • Add new MenuSection, MenuHeading, and MenuSeparator components
    • Add new simplified data-* attributes as an alternative to the existing data-headlessui-state="..." attribute
    • Add autoFocus prop on focusable components (which maps to data-autofocus)

    Changed

    • Bumped to React and React DOM 18
    • Dialog is focused by default instead of the first focusable element (unless an element exists with a data-autofocus in the dialog)
    Open source →
  32. 1.7.1915 Apr 2024
    Release notes
    • Fix Combobox activeOption render prop (#2973)
    Open source →
    Additional notes

    Fixed

    • Make sure panels re-register when IDs are calculated in React < 18 (#2883)
    • Expose disabled state on Tab component (#2918)
    • Prevent default behaviour when clicking outside of a Dialog.Panel (#2919)
    • Add hidden attribute to internal Hidden component when the Features.Hidden feature is used (#2955)
    • Allow setting custom tabIndex on the Switch component (#2966)
    • Forward disabled state to hidden inputs in form-like components (#3004)
    • Respect selectedIndex for controlled Tab components (#3037)
    Open source →
    Additional notes

    Fixed

    • Make sure panels re-register when IDs are calculated in React < 18 (#2883)
    • Expose disabled state on Tab component (#2918)
    • Prevent default behavior when clicking outside of a Dialog.Panel (#2919)
    • Add hidden attribute to internal Hidden component when the Features.Hidden feature is used (#2955)
    • Allow setting custom tabIndex on the Switch component (#2966)
    • Forward disabled state to hidden inputs in form-like components (#3004)
    • Respect selectedIndex for controlled Tab components (#3037)
    Open source →
  33. 1.7.188 Jan 2024
    Release notes

    Added

    • Allow users customize ID generation (#2959)
    Open source →
    Additional notes

    Fixed

    • Don't call <Dialog>'s onClose twice on mobile devices (#2690)
    • Lazily resolve default containers in <Dialog> (#2697)
    • Ensure hidden Tab.Panel components are hidden from the accessibility tree (#2708)
    • Add support for role="alertdialog" to <Dialog> component (#2709)
    • Ensure blurring the Combobox.Input component closes the Combobox (#2712)
    • Allow changes to the className prop when the <Transition /> component is currently not transitioning (#2722)
    • Export (internal-only) component interfaces for TypeScript compiler (#2313)
    • Fix infinite render-loop for <Disclosure.Panel> and <Popover.Panel> when as={Fragment} (#2760)
    • Fix VoiceOver bug for Listbox component in Chrome (#2824)
    • Fix outside click detection when component is mounted in the Shadow DOM (#2866)
    • Fix CJS types (#2880)
    • Fix error when transition classes contain new lines (#2871)
    • Improve iOS locking (7721aca)
    Open source →
    Additional notes

    Fixed

    • Don't call Dialog's onClose twice on mobile devices (#2690)
    • Lazily resolve default containers in Dialog (#2697)
    • Ensure hidden Tab.Panel components are hidden from the accessibility tree (#2708)
    • Add support for role="alertdialog" to Dialog component (#2709)
    • Ensure blurring the Combobox.Input component closes the Combobox (#2712)
    • Allow changes to the className prop when the Transition component is currently not transitioning (#2722)
    • Export (internal-only) component interfaces for TypeScript compiler (#2313)
    • Fix infinite render-loop for Disclosure.Panel and Popover.Panel when as={Fragment} (#2760)
    • Fix VoiceOver bug for Listbox component in Chrome (#2824)
    • Fix outside click detection when component is mounted in the Shadow DOM (#2866)
    • Fix CJS types (#2880)
    • Fix error when transition classes contain new lines (#2871)
    • Improve iOS locking (7721aca)
    Open source →
  34. 1.7.1717 Aug 2023
    Release notes

    Fixed

    • Don't call <Dialog>'s onClose twice on mobile devices (#2690)
    • Fix Portal SSR hydration mismatches (#2700)
    • Ensure hidden TabPanel components are hidden from the accessibility tree (#2708)
    • Add support for role="alertdialog" to <Dialog> component (#2709)
    • Ensure blurring the ComboboxInput component closes the Combobox (#2712)
    • Allow <button> to be in nested components in <PopoverButton> (#2715)
    • Don't overwrite user-defined template refs when rendering (#2720)
    • Fix missing data-headlessui-state attribute when as="template" (#2787)
    • Fix VoiceOver bug for Listbox component in Chrome (#2824)
    • Fix outside click detection when component is mounted in the Shadow DOM (6846231)
    • Fix CJS types (#2880)
    • Fix error when transition classes contain new lines (#2871)
    Open source →
    Additional notes

    Fixed

    • Use correct value when resetting <Listbox multiple> and <Combobox multiple> (#2626)
    • Render <MainTreeNode /> in Popover.Group component only (#2634)
    • Disable smooth scrolling when opening/closing Dialog components on iOS (#2635)
    • Don't assume <Tab /> components are available when setting the next index (#2642)
    • Fix incorrectly focused Combobox.Input component on page load (#2654)
    • Ensure appear works using the Transition component (even when used with SSR) (#2646)
    • Improve resetting values when using the nullable prop on the Combobox component (#2660)
    • Fix hydration of components inside <Suspense> (#2663)
    • Prevent scrolling when focusing a tab (#2674)
    Open source →
    Additional notes

    Fixed

    • Use correct value when resetting <Listbox multiple> and <Combobox multiple> (#2626)
    • Render MainTreeNode in Popover.Group component only (#2634)
    • Disable smooth scrolling when opening/closing Dialog components on iOS (#2635)
    • Don't assume Tab components are available when setting the next index (#2642)
    • Fix incorrectly focused Combobox.Input component on page load (#2654)
    • Ensure appear works using the Transition component (even when used with SSR) (#2646)
    • Improve resetting values when using the nullable prop on the Combobox component (#2660)
    • Fix hydration of components inside Suspense (#2663)
    • Prevent scrolling when focusing a tab (#2674)
    Open source →
  35. 1.7.1627 Jul 2023
    Release notes

    Fixed

    • Fix form elements for uncontrolled <Listbox multiple> and <Combobox multiple> (#2626)
    • Use correct value when resetting <Listbox multiple> and <Combobox multiple> (#2626)
    • Render <MainTreeNode /> in PopoverGroup component only (#2634)
    • Disable smooth scrolling when opening/closing Dialog components on iOS (#2635)
    • Don't assume <Tab /> components are available when setting the next index (#2642)
    • Improve SSR of the Disclosure component (#2645)
    • Fix incorrectly focused ComboboxInput component on page load (#2654)
    • Improve resetting values when using the nullable prop on the Combobox component (#2660)
    • Prevent scrolling when focusing a tab (#2674)
    Open source →
    Additional notes

    Fixed

    • Ensure the caret is in a consistent position when syncing the Combobox.Input value (#2568)
    • Improve "outside click" behaviour in combination with 3rd party libraries (#2572)
    • Ensure IME works on Android devices (#2580)
    • Calculate aria-expanded purely based on the open/closed state (#2610)
    • Submit form on Enter even if no submit-like button was found (#2613)
    Open source →
    Additional notes

    Fixed

    • Ensure the caret is in a consistent position when syncing the Combobox.Input value (#2568)
    • Improve "outside click" behavior in combination with 3rd party libraries (#2572)
    • Ensure IME works on Android devices (#2580)
    • Calculate aria-expanded purely based on the open/closed state (#2610)
    • Submit form on Enter even if no submit-like button was found (#2613)
    Open source →
  36. 1.7.151 Jun 2023
    Release notes

    Fixed

    • Ensure the caret is in a consistent position when syncing the Combobox.Input value (#2568)
    • Improve "outside click" behaviour in combination with 3rd party libraries (#2572)
    • Improve performance of Combobox component (#2574)
    • Ensure IME works on Android devices (#2580)
    • Calculate aria-expanded purely based on the open/closed state (#2610)
    • Submit form on Enter even if no submit-like button was found (#2613)
    Open source →
    Additional notes2 sources agree

    Added

    • [internal] add demo mode to Menu and Popover components (#2448)

    Fixed

    • Ensure FocusTrap is only active when the given enabled value is true (#2456)
    • Stop <Transition appear> from overwriting classes on re-render (#2457)
    • Improve control over Menu and Listbox options while searching (#2471)
    • Consider clicks inside iframes to be "outside" (#2485)
    • Ensure moving focus within a Portal component, does not close the Popover component (#2492)

    Changed

    • Move types condition to the front (#2469)
    Open source →
  37. 1.7.1412 Apr 2023
    Release notes

    Fixed

    • Fix memory leak in Popover component (#2430)
    • Ensure FocusTrap is only active when the given enabled value is true (#2456)
    • Ensure the exposed activeIndex is up to date for the Combobox component (#2463)
    • Improve control over Menu and Listbox options while searching (#2471)
    • Consider clicks inside iframes to be "outside" (#2485)
    • Ensure moving focus within a Portal component, does not close the Popover component (#2492)

    Changed

    • Move types condition to the front (#2469)
    Open source →
    Additional notes

    Fixed

    • Fix focus styles showing up when using the mouse (#2347)
    • Fix "Can't perform a React state update on an unmounted component." when using the Transition component (#2374)
    • Add FocusTrap event listeners once document has loaded (#2389)
    • Fix className hydration for <Transition appear> (#2390)
    • Improve Combobox types to improve false positives (#2411)
    • Merge className correctly when it’s a function (#2412)

    Added

    • Add form prop to form-like components such as RadioGroup, Switch, Listbox, and Combobox (#2356)
    Open source →
    Additional notes

    Fixed

    • Fix focus styles showing up when using the mouse (#2347)
    • Fix "Can't perform a React state update on an unmounted component." when using the Transition component (#2374)
    • Add FocusTrap event listeners once document has loaded (#2389)
    • Fix className hydration for <Transition appear> (#2390)
    • Improve Combobox types to improve false positives (#2411)
    • Merge className correctly when it’s a function (#2412)
    • Correctly handle IME composition in Combobox.Input (#2426)

    Added

    • Add form prop to form-like components such as RadioGroup, Switch, Listbox, and Combobox (#2356)
    Open source →
  38. 1.7.133 Mar 2023
    Release notes

    Fixed

    • Fix focus styles showing up when using the mouse (#2347)
    • Disable ComboboxInput when its Combobox is disabled (#2375)
    • Add FocusTrap event listeners once document has loaded (#2389)
    • Don't scroll-lock <Dialog> when wrapping transition isn't showing (#2422)
    • Ensure DOM ref is properly handled in the RadioGroup component (#2424)

    Added

    • Add form prop to form-like components such as RadioGroup, Switch, Listbox, and Combobox (#2356)
    Open source →
    Additional notes

    Fixed

    • Ensure Transition component completes if nothing is transitioning (#2318)
    • Enable native label behavior for <Switch> where possible (#2265)
    • Allow root containers from the Dialog component in the FocusTrap component (#2322)
    • Fix XYZPropsWeControl and cleanup internal TypeScript types (#2329)
    • Fix invalid warning when using multiple Popover.Button components inside a Popover.Panel (#2333)
    • Fix restore focus to buttons in Safari, when Dialog component closes (#2326)
    Open source →
    Additional notes

    Fixed

    • Ensure Transition component completes if nothing is transitioning (#2318)
    • Enable native label behavior for Switch where possible (#2265)
    • Allow root containers from the Dialog component in the FocusTrap component (#2322)
    • Fix XYZPropsWeControl and cleanup internal TypeScript types (#2329)
    • Fix invalid warning when using multiple Popover.Button components inside a Popover.Panel (#2333)
    • Fix restore focus to buttons in Safari, when Dialog component closes (#2326)
    Open source →
  39. 1.7.1224 Feb 2023
    Release notes

    Fixed

    • Enable native label behavior for <Switch> where possible (#2265)
    • Allow root containers from the Dialog component in the FocusTrap component (#2322)
    • Cleanup internal TypeScript types (#2329)
    • Fix restore focus to buttons in Safari, when Dialog component closes (#2326)
    • Ensure hooks in the FocusTrap component only apply when mounted (#2331)
    Open source →
    Additional notes2 sources agree

    Added

    • Add explicit props types for every component (#2282)

    Fixed

    • Ensure the main tree and parent Dialog components are marked as inert (#2290)
    • Fix nested Popover components not opening (#2293)
    • Make React types more compatible with other libraries (#2282)
    • Fix Dialog cleanup when the Dialog becomes hidden (#2303)
    Open source →
  40. 1.7.1115 Feb 2023
    Release notes

    Fixed

    • Ensure the main tree and parent Dialog components are marked as inert (#2290)
    • Fix nested Popover components not opening (#2293)
    • Fix change event incorrectly getting called on blur (#2296)
    • Fix Dialog cleanup when the Dialog becomes hidden (#2303)
    Open source →
    Additional notes2 sources agree

    Fixed

    • Ensure we handle null values for the dataRef correctly (#2258)
    • Move aria-multiselectable to [role=listbox] in the Combobox component (#2271)
    • Re-focus Combobox.Input when a Combobox.Option is selected (#2272)
    • Ensure we reset the activeOptionIndex if the active option is unmounted (#2274)
    • Improve Ref type for forwarded Switch's ref (#2277)
    • Start cleanup phase of the Dialog component when going into the Closing state (#2264)
    Open source →
  41. 1.7.106 Feb 2023
    Release notes

    Fixed

    • Don’t fire afterLeave event more than once for a given transition (#2267)
    • Move aria-multiselectable to [role=listbox] in the Combobox component (#2271)
    • Re-focus Combobox.Input when a Combobox.Option is selected (#2272)
    • Ensure we reset the activeOptionIndex if the active option is unmounted (#2274)
    • Start cleanup phase of the Dialog component when going into the Closing state (#2264)
    Open source →
    Additional notes2 sources agree

    Fixed

    • Revert "Use the import * as React from 'react' pattern (#2242)
    Open source →
  42. 1.7.93 Feb 2023
    Release notes

    Fixed

    • Don't break overflow when multiple dialogs are open at the same time (#2215)
    Open source →
    Additional notes2 sources agree

    Fixed

    • Fix SSR tab hydration when using Strict Mode in development (#2231)
    • Don't break overflow when multiple dialogs are open at the same time (#2215)
    • Fix "This Suspense boundary received an update before it finished hydrating" error in the Disclosure component (#2238)
    • Use the import * as React from 'react' pattern (#2242)
    Open source →
  43. 1.7.827 Jan 2023
    Release notes

    Fixed

    • Ensure disabled="false" is not incorrectly passed to the underlying DOM Node (#2138)
    • Fix arrow key handling in Tab (after DOM order changes) (#2145)
    • Fix Tab key with non focusable elements in Popover.Panel (#2147)
    • Don’t overwrite classes during SSR when rendering fragments (#2173)
    • Improve Combobox accessibility (#2153)
    • Fix crash when reading headlessuiFocusGuard of relatedTarget in the FocusTrap component (#2203)
    • Fix FocusTrap in Dialog when there is only 1 focusable element (#2172)
    • Improve Tabs wrapping around when controlling the component and overflowing the selectedIndex (#2213)
    • Fix shadow-root bug closing Dialog containers (#2217)

    Added

    • Allow setting tabIndex on the Tab.Panel (#2214)

    Changed

    • Adjust SSR detection mechanism (#2102)
    Open source →
    Additional notes

    Fixed

    • Fix SSR tab rendering on React 17 (#2102)
    • Fix arrow key handling in Tab (after DOM order changes) (#2145)
    • Fix false positive warning about using multiple <Popover.Button> components (#2146)
    • Fix Tab key with non focusable elements in Popover.Panel (#2147)
    • Fix false positive warning when using <Popover.Button /> in React 17 (#2163)
    • Fix failed to removeChild on Node bug (#2164)
    • Don’t overwrite classes during SSR when rendering fragments (#2173)
    • Improve Combobox accessibility (#2153)
    • Fix crash when reading headlessuiFocusGuard of relatedTarget in the FocusTrap component (#2203)
    • Fix FocusTrap in Dialog when there is only 1 focusable element (#2172)
    • Improve Tabs wrapping around when controlling the component and overflowing the selectedIndex (#2213)
    • Fix shadow-root bug closing Dialog containers (#2217)

    Added

    • Allow setting tabIndex on the Tab.Panel (#2214)
    Open source →
    Additional notes

    Fixed

    • Fix SSR tab rendering on React 17 (#2102)
    • Fix arrow key handling in Tab (after DOM order changes) (#2145)
    • Fix false positive warning about using multiple Popover.Button components (#2146)
    • Fix Tab key with non focusable elements in Popover.Panel (#2147)
    • Fix false positive warning when using Popover.Button in React 17 (#2163)
    • Fix failed to removeChild on Node bug (#2164)
    • Don’t overwrite classes during SSR when rendering fragments (#2173)
    • Improve Combobox accessibility (#2153)
    • Fix crash when reading headlessuiFocusGuard of relatedTarget in the FocusTrap component (#2203)
    • Fix FocusTrap in Dialog when there is only 1 focusable element (#2172)
    • Improve Tabs wrapping around when controlling the component and overflowing the selectedIndex (#2213)
    • Fix shadow-root bug closing Dialog containers (#2217)

    Added

    • Allow setting tabIndex on the Tab.Panel (#2214)
    Open source →
  44. 1.7.716 Dec 2022
    Release notes3 sources agree

    Fixed

    • Improve scroll restoration after Dialog closes (b20e48dd)
    Open source →
  45. 1.7.615 Dec 2022
    Release notes3 sources agree

    Fixed

    • Fix regression where displayValue crashes (#2087)
    • Fix displayValue syncing when Combobox.Input is unmounted and re-mounted in different trees (#2090)
    • Fix FocusTrap escape due to strange tabindex values (#2093)
    • Improve scroll locking on iOS (#2100, 28234b0e)
    Open source →
  46. 1.7.58 Dec 2022
    Release notes

    Fixed

    • Reset form-like components when the parent <form> resets (#2004)
    • Ensure Popover doesn't crash when focus is going to window (#2019)
    • Ensure shift+home and shift+end works as expected in the ComboboxInput component (#2024)
    • Improve syncing of the ComboboxInput value (#2042)
    • Fix crash when using multiple mode without value prop (uncontrolled) for Listbox and Combobox components (#2058)
    • Allow passing in your own id prop (#2060)
    • Add null as a valid type for Listbox and Combobox in Vue (#2064, #2067)
    • Improve SSR for Tabs in Vue (#2068)
    • Ignore pointer events in Listbox, Menu, and Combobox when cursor hasn't moved (#2069)
    • Allow clicks inside dialog panel when target is inside shadow root (#2079)
    Open source →
    Additional notes

    Fixed

    • Reset form-like components when the parent <form> resets (#2004)
    • Add warning when using <Popover.Button /> multiple times (#2007)
    • Ensure Popover doesn't crash when focus is going to window (#2019)
    • Ensure shift+home and shift+end works as expected in the Combobox.Input component (#2024)
    • Improve syncing of the Combobox.Input value (#2042)
    • Fix crash when using multiple mode without value prop (uncontrolled) for Listbox and Combobox components (#2058)
    • Apply enter and enterFrom classes in SSR for Transition component (#2059)
    • Allow passing in your own id prop (#2060)
    • Fix Dialog unmounting problem due to incorrect transitioncancel event in the Transition component on Android (#2071)
    • Ignore pointer events in Listbox, Menu, and Combobox when cursor hasn't moved (#2069)
    • Allow clicks inside dialog panel when target is inside shadow root (#2079)
    Open source →
    Additional notes

    Fixed

    • Reset form-like components when the parent form resets (#2004)
    • Add warning when using Popover.Button multiple times (#2007)
    • Ensure Popover doesn't crash when focus is going to window (#2019)
    • Ensure shift+home and shift+end works as expected in the Combobox.Input component (#2024)
    • Improve syncing of the Combobox.Input value (#2042)
    • Fix crash when using multiple mode without value prop (uncontrolled) for Listbox and Combobox components (#2058)
    • Apply enter and enterFrom classes in SSR for Transition component (#2059)
    • Allow passing in your own id prop (#2060)
    • Fix Dialog unmounting problem due to incorrect transitioncancel event in the Transition component on Android (#2071)
    • Ignore pointer events in Listbox, Menu, and Combobox when cursor hasn't moved (#2069)
    • Allow clicks inside dialog panel when target is inside shadow root (#2079)
    Open source →
  47. 1.7.43 Nov 2022
    Release notes

    Fixed

    • Expose close function for Menu and MenuItem components (#1897)
    • Fix useOutsideClick, add improvements for ShadowDOM (#1914)
    • Prevent default slot warning when using a component for as prop (#1915)
    • Fire <ComboboxInput>'s @change handler when changing the value internally (#1916)
    Open source →
    Additional notes

    Fixed

    • Fix <Popover.Button as={Fragment} /> crash (#1889)
    • Expose close function for Menu and Menu.Item components (#1897)
    • Fix useOutsideClick, add improvements for ShadowDOM (#1914)
    • Fire <Combobox.Input>'s onChange handler when changing the value internally (#1916)
    • Add client-only to mark everything as client components (#1981)

    Added

    • Warn when changing components between controlled and uncontrolled (#1878)
    Open source →
    Additional notes

    Fixed

    • Fix <Popover.Button as={Fragment} /> crash (#1889)
    • Expose close function for Menu and Menu.Item components (#1897)
    • Fix useOutsideClick, add improvements for ShadowDOM (#1914)
    • Fire Combobox.Input's onChange handler when changing the value internally (#1916)
    • Add client-only to mark everything as client components (#1981)

    Added

    • Warn when changing components between controlled and uncontrolled (#1878)
    Open source →
  48. 1.7.330 Sept 2022
    Release notes

    Fixed

    • Call displayValue with a v-model of ref(undefined) on ComboboxInput (#1865)
    • Improve Portal detection for Popover components (#1842)
    • Fix crash when children are undefined (#1885)
    • Fix useOutsideClick swallowing events inside ShadowDOM (#1876)
    • Fix Tab incorrectly activating on focus event (#1887)
    Open source →
    Additional notes2 sources agree

    Fixed

    • Improve Portal detection for Popover components (#1842)
    • Fix useOutsideClick swallowing events inside ShadowDOM (#1876)
    • Fix Tab incorrectly activating on focus event (#1887)
    Open source →
  49. 1.7.215 Sept 2022
    Release notes

    Fixed

    • Prevent option selection in ComboboxInput while composing (#1850)
    • Ensure we handle the static prop in TabPanel components correctly (#1856)
    Open source →
    Additional notes2 sources agree

    Fixed

    • Prevent option selection in Combobox.Input while composing (#1850)
    • Ensure we handle the static prop in Tab.Panel components correctly (#1856)
    Open source →
  50. 1.7.112 Sept 2022
    Release notes

    Fixed

    • Improve iOS scroll locking (#1830)
    • Ensure Tab order stays consistent, and the currently active Tab stays active (#1837)
    Open source →
    Additional notes2 sources agree

    Fixed

    • Improve iOS scroll locking (#1830)
    • Add <fieldset disabled> check to radio group options in React (#1835)
    • Ensure Tab order stays consistent, and the currently active Tab stays active (#1837)
    • Ensure Combobox.Label is properly linked when rendered after Combobox.Button and Combobox.Input components (#1838)
    • Remove forceRerender from Tab component (#1846)
    Open source →
  51. 1.7.06 Sept 2022
    Release notes

    Added

    • Add by prop for Listbox, Combobox and RadioGroup (#1482, #1717, #1814, #1815)
    • Make form components uncontrollable (#1683)
    • Add @headlessui/tailwindcss plugin (#1487)

    Fixed

    • Fixed SSR support on Deno (#1671)
    • Don’t close dialog when opened during mouse up event (#1667)
    • Don’t close dialog when drag ends outside dialog (#1667)
    • Fix outside clicks to close dialog when nested, unopened dialogs are present (#1667)
    • Close Menu component when using tab key (#1673)
    • Resync input when display value changes (#1679, #1755)
    • Ensure controlled Tabs don't change automagically (#1680)
    • Improve outside click on Safari iOS (#1712)
    • Improve event handler merging (#1715)
    • Fix incorrect scrolling to the bottom when opening a Dialog (#1716)
    • Don't overwrite element.focus() on <PopoverPanel> (#1719)
    • Improve Combobox re-opening keyboard issue on mobile (#1732)
    • Only select the active option when using "singular" mode when pressing <tab> in the Combobox component (#1750)
    • Only restore focus to the MenuButton if necessary when activating a MenuOption (#1782)
    • Don't scroll when wrapping around in focus trap (#1789)
    • Improve accessibility when announcing ListboxOption and ComboboxOption components (#1812)
    • Expose the value from the Combobox and Listbox components slot (#1822)
    • Improve scroll lock on iOS (#1824)
    Open source →
    Additional notes

    Added

    • Add by prop for Listbox, Combobox and RadioGroup (#1482, #1717, #1814, #1815)
    • Make form components uncontrollable (#1683)
    • Add @headlessui/tailwindcss plugin (#1487)

    Fixed

    • Fixed SSR support on Deno (#1671)
    • Don’t close dialog when opened during mouse up event (#1667)
    • Don’t close dialog when drag ends outside dialog (#1667)
    • Fix outside clicks to close dialog when nested, unopened dialogs are present (#1667)
    • Close Menu component when using tab key (#1673)
    • Resync input when display value changes (#1679, #1755)
    • Ensure controlled Tabs don't change automagically (#1680)
    • Don't scroll lock when a Transition + Dialog is mounted but hidden (#1681)
    • Allow Popover close to be passed directly to onClick handlers (#1696)
    • Improve outside click on Safari iOS (#1712)
    • Improve event handler merging (#1715)
    • Fix incorrect scrolling to the bottom when opening a Dialog (#1716)
    • Improve Combobox re-opening keyboard issue on mobile (#1732)
    • Ensure Disclosure.Panel is properly linked (#1747)
    • Only select the active option when using "singular" mode when pressing <tab> in the Combobox component (#1750)
    • Improve the types of the Combobox component (#1761)
    • Only restore focus to the Menu.Button if necessary when activating a Menu.Option (#1782)
    • Don't scroll when wrapping around in focus trap (#1789)
    • Fix Transition component's incorrect cleanup and order of events (#1803)
    • Ensure enter transitions work when using unmount={false} (#1811)
    • Improve accessibility when announcing Listbox.Option and Combobox.Option components (#1812)
    • Fix ref stealing from children (#1820)
    • Expose the value from the Combobox and Listbox components render prop (#1822)
    • Improve scroll lock on iOS (#1824)
    • Fix maximum call stack size exceeded error on Tab component when using as={Fragment} (#1826)
    • Fix "blank" screen on initial load of Transition component (#1823)
    Open source →
    Additional notes

    Added

    • Add by prop for Listbox, Combobox and RadioGroup (#1482, #1717, #1814, #1815)
    • Make form components uncontrollable (#1683)
    • Add @headlessui/tailwindcss plugin (#1487)

    Fixed

    • Fixed SSR support on Deno (#1671)
    • Don’t close dialog when opened during mouse up event (#1667)
    • Don’t close dialog when drag ends outside dialog (#1667)
    • Fix outside clicks to close dialog when nested, unopened dialogs are present (#1667)
    • Close Menu component when using tab key (#1673)
    • Resync input when display value changes (#1679, #1755)
    • Ensure controlled Tabs don't change automagically (#1680)
    • Don't scroll lock when a Transition + Dialog is mounted but hidden (#1681)
    • Allow Popover close to be passed directly to onClick handlers (#1696)
    • Improve outside click on Safari iOS (#1712)
    • Improve event handler merging (#1715)
    • Fix incorrect scrolling to the bottom when opening a Dialog (#1716)
    • Improve Combobox re-opening keyboard issue on mobile (#1732)
    • Ensure Disclosure.Panel is properly linked (#1747)
    • Only select the active option when using "singular" mode when pressing tab in the Combobox component (#1750)
    • Improve the types of the Combobox component (#1761)
    • Only restore focus to the Menu.Button if necessary when activating a Menu.Option (#1782)
    • Don't scroll when wrapping around in focus trap (#1789)
    • Fix Transition component's incorrect cleanup and order of events (#1803)
    • Ensure enter transitions work when using unmount={false} (#1811)
    • Improve accessibility when announcing Listbox.Option and Combobox.Option components (#1812)
    • Fix ref stealing from children (#1820)
    • Expose the value from the Combobox and Listbox components render prop (#1822)
    • Improve scroll lock on iOS (#1824)
    • Fix maximum call stack size exceeded error on Tab component when using as={Fragment} (#1826)
    • Fix "blank" screen on initial load of Transition component (#1823)
    Open source →
  52. 1.6.67 Jul 2022
    Release notes

    Fixed

    • Fix getting Vue dom elements (#1610)
    • Ensure CMD+Backspace works in nullable mode for Combobox component (#1617)
    • Properly merge incoming props with own props (#1651)
    • Ensure PopoverPanel can be used inside <transition> (#1653)
    Open source →
    Additional notes2 sources agree

    Fixed

    • Ensure CMD+Backspace works in nullable mode for Combobox component (#1617)
    Open source →
  53. 1.6.520 Jun 2022
    Release notes

    Fixed

    • Support <slot> children when using as="template" (#1548)
    • Improve outside click of Dialog component (#1546)
    • Detect outside clicks from within <iframe> elements (#1552)
    • Only render the Dialog on the client (#1566)
    • Improve Combobox input cursor position (#1574)
    • Fix scrolling issue in Tab component when using arrow keys (#1584)
    • Fix missing aria-expanded for ComboboxInput component (#1605)
    Open source →
    Additional notes

    Fixed

    • Fix incorrect transitionend/transitioncancel events for the Transition component (#1537)
    • Improve outside click of Dialog component (#1546)
    • Detect outside clicks from within <iframe> elements (#1552)
    • Improve Combobox input cursor position (#1574)
    • Fix scrolling issue in Tab component when using arrow keys (#1584)
    Open source →
    Additional notes

    Fixed

    • Fix incorrect transitionend/transitioncancel events for the Transition component (#1537)
    • Improve outside click of Dialog component (#1546)
    • Detect outside clicks from within iframe elements (#1552)
    • Improve Combobox input cursor position (#1574)
    • Fix scrolling issue in Tab component when using arrow keys (#1584)
    Open source →
  54. 1.6.429 May 2022
    Release notes

    Fixed

    • Ensure Escape propagates correctly in Combobox component (#1511)
    • Remove leftover code in Combobox component (#1514)
    Open source →
    Additional notes2 sources agree

    Fixed

    • Ensure Escape propagates correctly in Combobox component (#1511)
    • Remove leftover code in Combobox component (#1514)
    • Fix event handlers with arity > 1 (#1515)
    • Fix transition enter bug (#1519)
    • Fix render prop data in RadioGroup component (#1522)
    Open source →
  55. 1.6.325 May 2022
    Release notes

    Fixed

    • Allow to override the type on the ComboboxInput (#1476)
    • Ensure the the <PopoverPanel focus> closes correctly (#1477)
    • Only render the FocusSentinel if required in the Tabs component (#1493)
    Open source →
    Additional notes2 sources agree

    Fixed

    • Allow to override the type on the Combobox.Input (#1476)
    • Ensure the the <Popover.Panel focus> closes correctly (#1477)
    • Only render the FocusSentinel if required in the Tabs component (#1493)
    • Ensure the Transition stops once DOM Nodes are hidden (#1500)
    Open source →
  56. 1.6.219 May 2022
    Release notes

    Fixed

    • Ensure DialogPanel exposes its ref (#1404)
    • Ignore Escape when event got prevented in Dialog component (#1424)
    • Improve FocusTrap behaviour (#1432)
    • Simplify Popover Tab logic by using sentinel nodes instead of keydown event interception (#1440)
    • Ensure the PopoverPanel is clickable without closing the Popover (#1443)
    • Improve "Scroll lock" scrollbar width for Dialog component (#1457)
    • Don’t throw when SSR rendering internal portals in Vue (#1459)
    Open source →
    Additional notes

    Fixed

    • Fix closing of Popover.Panel in React 18 (#1409)
    • Ignore Escape when event got prevented in Dialog component (#1424)
    • Improve FocusTrap behaviour (#1432)
    • Simplify Popover Tab logic by using sentinel nodes instead of keydown event interception (#1440)
    • Ensure the Popover.Panel is clickable without closing the Popover (#1443)
    • Improve "Scroll lock" scrollbar width for Dialog component (#1457)
    • Make the ref optional in the Popover component (#1465)
    • Ensure the ref is forwarded on the Transition.Child component (#1473)
    Open source →
    Additional notes

    Fixed

    • Fix closing of Popover.Panel in React 18 (#1409)
    • Ignore Escape when event got prevented in Dialog component (#1424)
    • Improve FocusTrap behavior (#1432)
    • Simplify Popover Tab logic by using sentinel nodes instead of keydown event interception (#1440)
    • Ensure the Popover.Panel is clickable without closing the Popover (#1443)
    • Improve "Scroll lock" scrollbar width for Dialog component (#1457)
    • Make the ref optional in the Popover component (#1465)
    • Ensure the ref is forwarded on the Transition.Child component (#1473)
    Open source →
  57. 1.6.13 May 2022
    Release notes

    Fixed

    • Manually passthrough attrs for Combobox, Listbox and TabsGroup component (#1372)
    • Fix enter transitions in Vue (#1395)
    Open source →
    Additional notes2 sources agree

    Fixed

    • Fix hydration issue with Tab component (#1393)
    Open source →
  58. 1.6.025 Apr 2022
    Release notes

    Fixed

    • Make sure that the input syncs when the combobox closes (#1137)
    • Ensure that you can close the Combobox initially (#1148)
    • Fix Dialog usage in Tab component (#1149)
    • Ensure links are triggered inside PopoverPanel components (#1153)
    • Fix hover scroll issue in Listbox, Combobox and Menu components (#1161)
    • Guarantee DOM sort order when performing Listbox, Combobox and Menu actions (#1168)
    • Improve outside click support (#1175)
    • Reset ComboboxInput when the value gets reset (#1181)
    • Adjust active item/option index on Listbox, Combobox and Menu components (#1184)
    • Fix re-focusing element after close (#1186)
    • Fix Dialog cycling (#553)
    • Only activate the Tab on mouseup (#1192)
    • Ignore "outside click" on removed elements (#1193)
    • Remove focus() from Listbox.Option (#1218)
    • Improve some internal code (#1221)
    • Don't drop initial character when searching in Combobox (#1223)
    • Use ownerDocument instead of document (#1158)
    • Fix, re-expose el from each component (#1230)
    • Ensure focus trapping plays well with the Tab and Dialog components (#1231)
    • Improve syncing of ComboboxInput value (#1248)
    • Fix tree-shaking support (#1247)
    • Stop propagation on the PopoverButton (#1263)
    • Fix incorrect closing while interacting with third party libraries in Dialog component (#1268)
    • Mimic browser select on focus when navigating via Tab (#1272)
    • Resolve initialFocusRef correctly (#1276)
    • Ensure that there is always an active option in the Combobox (#1279, #1281)
    • Support classic form submissions in RadioGroup, Switch and Combobox components (#1285)
    • Fix nullable prop for Vue (2b109548b1a94a30858cf58c8f525554a1c12cbb)
    • Prefer incoming open prop over OpenClosed state (#1360)

    Added

    • Add classic form submission compatibility via new hidden inputs (#1214)
    • Add multiple value support to Listbox and Combobox components (#1243, #1355)
    • Add support for clearing the value of a Combobox (#1295)
    • Add DialogPanel to resolve issues when scrolling long dialogs that use DialogOverlay (#1333)

    Changes that might affect you

    Migrating from DialogOverlay to DialogPanel

    In previous versions of Headless UI, closing a dialog was handled by a click handler that lived on the DialogOverlay component, so as long as your overlay was rendered behind your panel, clicking outside the panel would close the dialog.

    This created an issue with scrollable dialogs, because it became easy to accidentally position your overlay on top of the scrollbar, which made it impossible to click the scrollbar without closing the dialog. You also couldn't scroll the dialog when your mouse was hovering over the overlay — only when your mouse was hovering over the actual panel.

    We've fixed this in Headless UI v1.6 by adding a dedicated DialogPanel component, and changing how "click outside" is handled. Now, if you're using a DialogPanel, the dialog is closed any time you click any element outside of it, rather than closing only when a DialogOverlay is explicitly clicked.

    If you're using DialogOverlay and not using DialogPanel, everything will continue to work exactly as it did before (including the bug I described above) to preserve backwards compatibility, but we highly encourage you to migrate to using DialogPanel, and to stop using DialogOverlay, instead using a simple div element:

      <Dialog
    :open="isOpen"
    @close="closeModal"
    class="fixed inset-0 flex items-center justify-center ..."
  >
-   <DialogOverlay class="fixed inset-0 bg-black/25" />
+   <div class="fixed inset-0 bg-black/25" />
  
-   <div class="bg-white shadow-xl rounded-2xl ...">
+   <DialogPanel class="bg-white shadow-xl rounded-2xl ...">
      <DialogTitle>Payment successful</DialogTitle>
      <!-- ... -->
-   </div>
+   </DialogPanel>
  </Dialog>

    Read through the updated Dialog documentation for more examples of using DialogPanel.

    Multiple value support for Listbox and Combobox

    If you have been using the insiders build for the new multiple value support for the Listbox and/or Combobox component, then you will have to add a new multiple prop to those components to tell the component that you are using multiple values. Previously this was automatically detected based on whether you were passing an array to the value prop or not.

    -  <Listbox v-model="selectedPeople" />
+  <Listbox v-model="selectedPeople" multiple />
    Open source →
    Additional notes

    Fixed

    • Ensure that you can add the ref prop to all components (#1116)
    • Ensure links are triggered inside Popover.Panel components (#1153)
    • Improve SSR for Tab component (#1155)
    • Fix hover scroll issue in Listbox, Combobox and Menu components (#1161)
    • Guarantee DOM sort order when performing Listbox, Combobox and Menu actions (#1168)
    • Fix <Transition> flickering issue (#1118)
    • Improve outside click support (#1175)
    • Ensure that appear prop on the <Transition> component works regardless of multiple rerenders (#1179)
    • Reset Combobox.Input when the value gets reset (#1181)
    • Fix double beforeEnter callback on the <Transition> component caused by SSR (#1183)
    • Adjust active item/option index on Listbox, Combobox and Menu components (#1184)
    • Only activate the Tab on mouseup (#1192)
    • Ignore "outside click" on removed elements (#1193)
    • Remove focus() from Listbox.Option (#1218)
    • Improve some internal code (#1221)
    • Use ownerDocument instead of document (#1158)
    • Ensure focus trapping plays well with the Tab and Dialog components (#1231)
    • Improve syncing of Combobox.Input value (#1248)
    • Fix tree-shaking support (#1247)
    • Stop propagation on the Popover.Button (#1263)
    • Fix incorrect active option in the Listbox and Combobox components (#1264)
    • Properly merge incoming props (#1265)
    • Fix incorrect closing while interacting with third party libraries in Dialog component (#1268)
    • Mimic browser select on focus when navigating the Tab component (#1272)
    • Ensure that there is always an active option in the Combobox (#1279, #1281)
    • Support classic form submissions in RadioGroup, Switch and Combobox components (#1285)
    • Add React 18 compatibility (#1326)
    • Fix open/closed state issue in Dialog (#1360)

    Added

    • Add classic form submission compatibility via new hidden inputs (#1214)
    • Add multiple value support to Listbox and Combobox components (#1243, #1355)
    • Add support for clearing the value of a Combobox (#1295)
    • Add Dialog.Panel to resolve issues when scrolling long dialogs that use Dialog.Overlay (#1333)

    Changes that might affect you

    Migrating from Dialog.Overlay to Dialog.Panel

    In previous versions of Headless UI, closing a dialog was handled by a click handler that lived on the Dialog.Overlay component, so as long as your overlay was rendered behind your panel, clicking outside the panel would close the dialog.

    This created an issue with scrollable dialogs, because it became easy to accidentally position your overlay on top of the scrollbar, which made it impossible to click the scrollbar without closing the dialog. You also couldn't scroll the dialog when your mouse was hovering over the overlay — only when your mouse was hovering over the actual panel.

    We've fixed this in Headless UI v1.6 by adding a dedicated Dialog.Panel component, and changing how "click outside" is handled. Now, if you're using a Dialog.Panel, the dialog is closed any time you click any element outside of it, rather than closing only when a Dialog.Overlay is explicitly clicked.

    If you're using Dialog.Overlay and not using Dialog.Panel, everything will continue to work exactly as it did before (including the bug I described above) to preserve backwards compatibility, but we highly encourage you to migrate to using Dialog.Panel, and to stop using Dialog.Overlay, instead using a simple div element:

      <Dialog
    open={isOpen}
    onClose={closeModal}
    className="fixed inset-0 flex items-center justify-center ..."
  >
-   <Dialog.Overlay className="fixed inset-0 bg-black/25" />
+   <div className="fixed inset-0 bg-black/25" />
  
-   <div className="bg-white shadow-xl rounded-2xl ...">
+   <Dialog.Panel className="bg-white shadow-xl rounded-2xl ...">
      <Dialog.Title>Payment successful</Dialog.Title>
      {/* ... */}
-   </div>
+   </Dialog.Panel>
  </Dialog>

    Read through the updated Dialog documentation for more examples of using Dialog.Panel.

    Multiple value support for Listbox and Combobox

    If you have been using the insiders build for the new multiple value support for the Listbox and/or Combobox component, then you will have to add a new multiple prop to those components to tell the component that you are using multiple values. Previously this was automatically detected based on whether you were passing an array to the value prop or not.

    -  <Listbox value={selectedPeople} onChange={setSelectedPeople} />
+  <Listbox value={selectedPeople} onChange={setSelectedPeople} multiple />
    Open source →
    Additional notes

    Fixed

    • Ensure that you can add the ref prop to all components (#1116)
    • Ensure links are triggered inside Popover.Panel components (#1153)
    • Improve SSR for Tab component (#1155)
    • Fix hover scroll issue in Listbox, Combobox and Menu components (#1161)
    • Guarantee DOM sort order when performing Listbox, Combobox and Menu actions (#1168)
    • Fix Transition flickering issue (#1118)
    • Improve outside click support (#1175)
    • Ensure that appear prop on the Transition component works regardless of multiple rerenders (#1179)
    • Reset Combobox.Input when the value gets reset (#1181)
    • Fix double beforeEnter callback on the Transition component caused by SSR (#1183)
    • Adjust active item/option index on Listbox, Combobox and Menu components (#1184)
    • Only activate the Tab on mouseup (#1192)
    • Ignore "outside click" on removed elements (#1193)
    • Remove focus() from Listbox.Option (#1218)
    • Improve some internal code (#1221)
    • Use ownerDocument instead of document (#1158)
    • Ensure focus trapping plays well with the Tab and Dialog components (#1231)
    • Improve syncing of Combobox.Input value (#1248)
    • Fix tree-shaking support (#1247)
    • Stop propagation on the Popover.Button (#1263)
    • Fix incorrect active option in the Listbox and Combobox components (#1264)
    • Properly merge incoming props (#1265)
    • Fix incorrect closing while interacting with third party libraries in Dialog component (#1268)
    • Mimic browser select on focus when navigating the Tab component (#1272)
    • Ensure that there is always an active option in the Combobox (#1279, #1281)
    • Support classic form submissions in RadioGroup, Switch and Combobox components (#1285)
    • Add React 18 compatibility (#1326)
    • Fix open/closed state issue in Dialog (#1360)

    Added

    • Add classic form submission compatibility via new hidden inputs (#1214)
    • Add multiple value support to Listbox and Combobox components (#1243, #1355)
    • Add support for clearing the value of a Combobox (#1295)
    • Add Dialog.Backdrop and Dialog.Panel components (#1333)
    Open source →
  59. 1.5.017 Feb 2022
    Release notes

    Fixed

    • Ensure correct order when conditionally rendering MenuItem, ListboxOption and RadioGroupOption (#1045)
    • Improve typeahead search logic (#1051)
    • Improve overall codebase, use modern tech like esbuild and TypeScript 4! (#1055)
    • Improve build files (#1078)
    • Ensure typeahead stays on same item if it still matches (#1098)

    Added

    Open source →
    Additional notes

    Fixed

    • Ensure correct order when conditionally rendering Menu.Item, Listbox.Option and RadioGroup.Option (#1045)
    • Improve controlled Tabs behaviour (#1050)
    • Improve typeahead search logic (#1051)
    • Improve overall codebase, use modern tech like esbuild and TypeScript 4! (#1055)
    • Improve build files (#1078)
    • Ensure typeahead stays on same item if it still matches (#1098)
    • Fix off-by-one frame issue causing flicker (#1111)
    • Trigger scrollIntoView effect when position changes (#1113)

    Added

    Open source →
    Additional notes

    Fixed

    • Ensure correct order when conditionally rendering Menu.Item, Listbox.Option and RadioGroup.Option (#1045)
    • Improve controlled Tabs behavior (#1050)
    • Improve typeahead search logic (#1051)
    • Improve overal codebase, use modern tech like esbuild and TypeScript 4! (#1055)
    • Improve build files (#1078)
    • Ensure typeahead stays on same item if it still matches (#1098)
    • Fix off-by-one frame issue causing flicker (#1111)
    • Trigger scrollIntoView effect when position changes (#1113)

    Added

    Open source →
  60. 1.4.314 Jan 2022
    Release notes

    Fixes

    • Fix missing key binding in examples (#1036, #1006)
    • Fix slice => splice typo in Tabs component (#1037, #986)
    • Ensure correct DOM node order when performing focus actions (#1038)

    Added

    • Allow for TabGroup to be controllable (#909, #970)
    Open source →
    Additional notes2 sources agree

    Fixes

    • Ensure portal root exists in the DOM (#950)
    • Ensure correct DOM node order when performing focus actions (#1038)

    Added

    • Allow for Tab.Group to be controllable (#909, #970)
    Open source →