Computes coordinates to position a floating element next to another element.
At its most basic, the function accepts two elements:
- Reference element — also known as the anchor element, this is the element that is being referred to for positioning. Often this is a button that triggers a floating popover like a tooltip or menu.
- Floating element — this is the element that floats next to the reference element, remaining anchored to it. This is the popover or tooltip itself.
First, give the floating element initial CSS styles so that it becomes an absolutely-positioned element that floats on top of the UI with layout ready for being measured:
Then, ensuring that these two elements are rendered onto the
document and can be measured, call
them as arguments.
The first argument is the reference element to anchor to, and the second argument is the floating element to be positioned.
computePosition() returns a
resolves with the coordinates that can be used to apply styles to
the floating element.
By default, the floating element will be placed at the bottom center of the reference element.
To ensure positioning works smoothly, the dimensions of the floating element should not change before and after being positioned.
Certain CSS styles must be applied before
computePosition() is called:
This makes the element float on top of the UI with intrinsic
dimensions based on the content, instead of acting as a block.
left coordinates can then take
width: max-content(or a fixed value)
These properties prevent the floating element from resizing when it overflows a container, removing layout interference that can cause incorrect measurements.
This lets you place the floating element anywhere in the DOM tree and have it be positioned correctly, regardless of the CSS styles of any ancestor containers.
computePosition() is only a single function call, it
only positions the floating element once.
To ensure it remains anchored to the reference element in a
variety of scenarios, such as when resizing or scrolling, wrap
the calculation in
Passed as a third argument, this is the object to configure the behavior.
Where to place the floating element relative to its reference
element. By default, this is
12 strings are available:
-end alignments are
and will adapt to the writing direction (e.g. RTL) as expected.
This is the type of CSS position property to use. Two strings are available:
Ensure your initial layout matches the strategy:
These strategies are differentiated as follows:
'absolute'— the floating element is positioned relative to its nearest positioned ancestor. With most layouts, this usually requires the browser to do the least work when updating the position.
'fixed'— the floating element is positioned relative to its nearest containing block (usually the viewport). This is useful when the reference element is also fixed to reduce jumpiness with positioning while scrolling. It will in many cases also “break” the floating element out of a clipping ancestor.
When you want granular control over how the floating element is
positioned, middleware are used. They read the current
coordinates, optionally alter them, and/or provide data for
rendering. They compose and work together to produce the final
coordinates which you receive as
The following are included in the package:
These middleware alter the base placement coordinates.
offsetmodifies the placement to add distance or margin between the reference and floating elements.
inlinepositions the floating element relative to individual client rects rather than the bounding box for better precision.
These middleware alter the coordinates to ensure the floating element stays on screen optimally.
shiftprevents the floating element from overflowing a clipping container by shifting it to stay in view.
flipprevents the floating element from overflowing a clipping container by flipping it to the opposite placement to stay in view.
autoPlacementautomatically chooses a placement for you using a “most space” strategy.
sizeresizes the floating element, for example so it will not overflow a clipping container, or to match the width of the reference element.
These middleware only provide data and do not alter the coordinates.
arrowprovides data to position an inner element of the floating element such that it is centered to its reference element.
hideprovides data to hide the floating element in applicable situations when it no longer appears attached to its reference element due to different clipping contexts.
You can also craft your own custom middleware to extend the behavior of the library. Read Middleware to learn how to create your own.
Middleware can be called conditionally inside the array inline for ergonomics:
Often this is useful for higher-level wrapper functions to avoid needing the consumer to import middleware themselves:
computePosition() returns the following type:
The x-coordinate of the floating element.
The y-coordinate of the floating element.
The final placement of the floating element, which may be different from the initial or preferred one passed in due to middleware modifications. This allows you to know which side the floating element is placed at.
The CSS position property to use.
The data returned by any middleware used.