A toolkit to position and create interactions for floating elements with React.
If you only need positioning without interactions, use the following for a smaller bundle size:
Choose the package you installed for better docs:
The goal of this package is to provide primitives to create components for tooltips, popovers, dropdown menus, hover cards, modal dialogs, select menus, comboboxes, and more. Instead of providing any pre-built components, it gives you the tools to create them more easily. This is ideal if you want lots of control, but does require more work to get started. The full guides in React Examples contain some copy-pasteable examples to get you started more quickly.
Floating UI’s usage can be broken down into two disparate parts:
- Positioning (available for both
- Interactions (available for just
useFloating() is the main hook of each package.
At its most basic, the Hook returns a
refs object and
This will position the floating
Tooltip element at the bottom
center of the
Button element by default.
refs.setReferenceis the reference (or anchor) element that is being referred to for positioning.
refs.setFloatingis the floating element that is being positioned relative to the reference element.
floatingStylesis an object of positioning styles to apply to the floating element’s
The refs are functions to make them reactive — this ensures changes to the reference or floating elements, such as with conditional rendering, are handled correctly by updating the position.
To ensure the floating element remains anchored to the reference
element, such as when scrolling or resizing, pass
autoUpdate to the
Visit the full
useFloating API docs for
detailed information about customizing the positioning of
When testing your components, ensure you flush microtasks
immediately after the floating element renders. This will avoid
You may use this a lot, so you can create a custom function:
Due to virtual elements, you may need to narrow the type when performing DOM operations on the ref:
To add interactions, such as the ability to only show a floating element while hovering over its reference element, the Hook must first accept the following two options:
open— a boolean that represents whether the floating element is currently rendered.
onOpenChange— an event callback invoked when the open boolean state should change.
Note that floating components do not always require “anchor
floatingStyles can be ignored.
Interaction Hooks allow the open state to change, among other
functionality. Each interaction Hook accepts the
context object which gets returned from
useFloating() as their first argument:
useFocus() Hooks set up Effects
and return event handler props to change the open state, the
latter of which get merged by
This API enables each of the Hooks to be fully tree-shakeable and opt-in. The navigation bar on the left explains them in detail.
The prop getters are used to add event handlers returned from the
interaction Hooks, among other functionality, to the reference
and floating elements. When called, they return an object of
onOpenChange event callback is invoked with an
object and reason
string as the second and third parameter:
onOpenChange is not called if you
manually changed the open state via the
setter. You can derive the event yourself in this case anyway.
refs.setReferenceelement is both the events and position reference by default.
refs.setPositionReferenceallows you to separate the position to another element (either real or virtual).
Refs can be merged with the
useMergeRefs hook, and props
can be merged by calling one of the getters inside of the other:
Disabled elements don’t fire events, so tooltips attached to
disabled buttons don’t show. Avoid using the
disabled prop, and make the button visually disabled
instead. This ensures you won’t need any wrapper tags and makes
the tooltip accessible to all users.