@headlessui/[email protected]

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)

@headlessui/[email protected]

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)

@headlessui/[email protected]

Fixed

• Manually passthrough attrs for Combobox, Listbox and TabsGroup component (#1372)
• Fix enter transitions in Vue (#1395)

@headlessui/[email protected]

Fixed

• Fix hydration issue with Tab component (#1393)

@headlessui/[email protected]

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

@headlessui/[email protected]

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

@headlessui/[email protected]

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

• Add Combobox component (#1047, #1099, #1101, #1104, #1106, #1109)

@headlessui/[email protected]

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

• Add Combobox component (#1047, #1099, #1101, #1104, #1109)

@headlessui/[email protected]

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)

@headlessui/[email protected]

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)