@headlessui/react
2.2.10 · 7 Apr 2026MIT10.3M / weekRepositoryHomepagenpmAtom feed
1.7.19 is the newest release of 1.x.
In short
1 removed5 new26 fixed
- Removed
Remove
focus()fromListbox.Option
Release note
Fixed
Ensure that you can add the
refprop to all componentsEnsure links are triggered inside
Popover.PanelcomponentsImprove SSR for
TabcomponentFix
hoverscroll issue inListbox,ComboboxandMenucomponentsGuarantee DOM sort order when performing
Listbox,ComboboxandMenuactionsFix
<Transition>flickering issueImprove outside click support
Ensure that
appearprop on the<Transition>component works regardless of multiple rerendersReset
Combobox.Inputwhen the value gets resetFix double
beforeEntercallback on the<Transition>component caused by SSRAdjust active
item/optionindex onListbox,ComboboxandMenucomponentsOnly activate the
Tabon mouseupIgnore "outside click" on removed elements
- Removed
Remove
focus()fromListbox.Option Improve some internal code
Use
ownerDocumentinstead ofdocumentEnsure focus trapping plays well with the
TabandDialogcomponentsImprove syncing of
Combobox.InputvalueFix tree-shaking support
Stop propagation on the
Popover.ButtonFix incorrect
activeoption in theListboxandComboboxcomponentsProperly merge incoming props
Fix incorrect closing while interacting with third party libraries in
DialogcomponentMimic browser select on focus when navigating the
TabcomponentEnsure that there is always an active option in the
Combobox(#1279, #1281)Support classic form submissions in
RadioGroup,SwitchandComboboxcomponentsAdd React 18 compatibility
Fix open/closed state issue in
Dialog
Added
Add classic form submission compatibility via new hidden inputs
Add multiple value support to
ListboxandComboboxcomponents (#1243, #1355)Add support for clearing the value of a
ComboboxAdd
Dialog.Panelto resolve issues when scrolling long dialogs that useDialog.Overlay
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 />A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.