Quick Start

Headless UI Float is a package that makes it easy to position floating elements in Headless UI, it uses Floating UI (new version Popper.js) for positioning.

TIP

Headless UI has released version 2.0 (currently for React only), which builds in anchor positioning with Floating UI, making this package unnecessary.

You can reference the Headless UI Menu example to use the transition for the menu or other components.

Online demo

You can try Headless UI Float online on StackBlitz:

• React
• React + TS

Installation

This package is require React v18, React DOM and @headlessui/react v1, you must be installed them first.

npm

npm i @headlessui-float/react

yarn

yarn add @headlessui-float/react

pnpm

pnpm add @headlessui-float/react

Usage

Start by finding a Headless UI component that needs to position the element, such as the <Menu> component for this example. Import <Float> component:

import { Float } from '@headlessui-float/react'

Then wrap <Float> around <Menu.Button> and <Menu.Items>:

<Menu>
  <Float>
    <Menu.Button className="...">
      Options
    </Menu.Button>

    <Menu.Items className="...">
      ...
    </Menu.Items>
  </Float>
</Menu>

Note that <Float> must contain 2 child elements, the first is the reference element, and the second is the floating element. It can be a Headless UI component or an HTML element.

INFO

If you want to use HTML elements, or manually control the display of Headless UI components, reference Show/hide.

Then remove the absolute, right-0 and other positioning class from <Menu.Items>, and add the placement="bottom-end" attribute:

<Menu>
  <Float placement="bottom-end">
    ...
  </Float>
</Menu>

Remove the mt-2 class from <Menu.Items>, and add the offset={4} attribute:

<Menu>
  <Float placement="bottom-end" offset={4}>
    ...
  </Float>
</Menu>

Then <Menu> can automatically position the inner <Menu.Items>.

In addition to <Menu>, the same can be used on <Listbox>, <Popover> or <Combobox> components, and you can use <Float> on any element that requires floating positioning.