Platform
Use Floating UI’s positioning logic on any platform that can execute JavaScript.
Floating UI’s core is essentially a bunch of mathematical calculations performed on rectangles. These calculations are pure and agnostic, allowing Floating UI to work on any platform that can execute JavaScript.
To make it work with a given platform, methods are used to allow it to hook into measurement APIs, for instance, to measure the bounding box of a given element.
Possible platforms other than the DOM include React Native, Canvas/WebGL, etc.
This is Floating UI running in a pure <canvas />
element!
Check it out on CodeSandbox.
Custom platform object
If you’re building a platform from scratch, e.g. your own tiny
custom DOM platform, you’ll be using the @floating-ui/core
package — see Methods.
If you’re extending or customizing the existing DOM methods, and
are using @floating-ui/dom
, this is accessible via the
platform
import:
Shadow DOM fix
There’s an unfortunate platform gap regarding offsetParent
where the spec says to hide the actual CSS offsetParent
inside
shadow DOM hierarchies, notable when using web components. This
causes the position to be wrong when a positioned parent has a
shadowed child floating element. Since Chrome 109, the
offsetParent
property now matches the spec, as well as Safari
and Firefox for quite some time, which causes the positioning
issue.
In many cases, using the 'fixed'
strategy instead of
'absolute'
will fix this positioning issue, but in case it
does not, you can add the following “ponyfill”:
Concepts
The library works largely with a Rect
:
This data can come from anywhere, and the library will perform
the right computations. x
and y
represent the
coordinates of the element relative to another one.
Methods
A platform
is a plain object consisting of 3 required
and 7 optional methods. These methods allow the platform to
interface with Floating UI’s logic.
Each of these methods can be either async or sync. This enables support of platforms whose measurement APIs are async, like React Native.
Required methods
getElementRects
Takes in the elements and the positioning strategy
and
returns the element Rect
objects.
reference
The x
and y
values of a reference
Rect
should be its coordinates relative to the
floating element’s offsetParent
element if required rather than
the viewport.
floating
Both x
and y
are not relevant initially, so you
can set these both of these to 0
.
getDimensions
Returns the dimensions of an element.
getClippingRect
Returns the Rect
(relative to the viewport) whose
outside bounds will clip the given element. For instance, the
viewport itself.
Optional methods
Depending on the platform you’re working with, these may or may not be necessary.
convertOffsetParentRelativeRectToViewportRelativeRect
This function will take a Rect
that is relative to a
given offsetParent
element and convert its x
and y
values such that it is instead relative to the
viewport.
getOffsetParent
Returns the offsetParent
of a given element. The following four
properties are what is accessed on an offsetParent
.
The polyfill
parameter exists only for
@floating-ui/dom
and is optional to fix the
Shadow DOM bug.
getDocumentElement
Returns the document element.
getClientRects
Returns an array of ClientRect
s.
isElement
Determines if the current value is an element.
isRTL
Determines if an element is in RTL layout.
getScale
Determines the scale of an element.
Usage
All these methods are passed to platform
: