Platform
Floating UI works on any platform that can run JavaScript, as long as it has adequate measurement APIs for elements. Possible platforms other than the DOM include React Native, Canvas/WebGL, etc.
The library works largely with a Rect
Rect
:
interface Rect {
width: number;
height: number;
x: number;
y: number;
}
interface Rect {
width: number;
height: number;
x: number;
y: number;
}
This data can come from anywhere, and the library will perform
the right computations. x
x
and y
y
represent the coordinates of the element relative to another one.
import {computePosition} from '@floating-ui/core';
computePosition(referenceElement, floatingElement, {
platform: {
// ...
},
});
import {computePosition} from '@floating-ui/core';
computePosition(referenceElement, floatingElement, {
platform: {
// ...
},
});
Methods
A platform
platform
is a plain object consisting of 3
required and 6 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
strategy
and returns the element Rect
Rect
objects.
function getElementRects({reference, floating, strategy}) {
return {
reference: {width: 0, height: 0, x: 0, y: 0},
floating: {width: 0, height: 0, x: 0, y: 0},
};
}
function getElementRects({reference, floating, strategy}) {
return {
reference: {width: 0, height: 0, x: 0, y: 0},
floating: {width: 0, height: 0, x: 0, y: 0},
};
}
reference
The x
x
and y
y
values of a reference
Rect
Rect
should be its coordinates relative to the
floating element’s offsetParent
element if required rather than
the viewport.
floating
Both x
x
and y
y
are not relevant
initially, so you can set these both of these to 0
0
.
getDimensions
Returns the dimensions of an element.
function getDimensions(element) {
return {width: 0, height: 0};
}
function getDimensions(element) {
return {width: 0, height: 0};
}
getClippingRect
Returns the Rect
Rect
(relative to the viewport) whose
outside bounds will clip the given element. For instance, the
viewport itself.
function getClippingRect({element, boundary, rootBoundary}) {
return {
width: 0,
height: 0,
x: 0,
y: 0,
};
}
function getClippingRect({element, boundary, rootBoundary}) {
return {
width: 0,
height: 0,
x: 0,
y: 0,
};
}
Optional methods
Depending on the platform you’re working with, these may or may not be necessary.
convertOffsetParentRelativeRectToViewportRelativeRect
This function will take a Rect
Rect
that is relative to a
given offsetParent
offsetParent
element and convert its
x
x
and y
y
values such that it is
instead relative to the viewport.
function convertOffsetParentRelativeRectToViewportRelativeRect({
rect,
offsetParent,
strategy,
}) {
return rect;
}
function convertOffsetParentRelativeRectToViewportRelativeRect({
rect,
offsetParent,
strategy,
}) {
return rect;
}
getOffsetParent
Returns the offsetParent
of a given element. The following four
properties are what is accessed on an offsetParent
.
function getOffsetParent(element) {
return {
clientWidth: 0,
clientHeight: 0,
clientLeft: 0,
clientTop: 0,
};
}
function getOffsetParent(element) {
return {
clientWidth: 0,
clientHeight: 0,
clientLeft: 0,
clientTop: 0,
};
}
getDocumentElement
Returns the document element.
function getDocumentElement(element) {
return {};
}
function getDocumentElement(element) {
return {};
}
getClientRects
Returns an array of ClientRect
ClientRect
s.
function getClientRects(element) {
return [];
}
function getClientRects(element) {
return [];
}
isElement
Determines if the current value is an element.
function isElement(value) {
return true;
}
function isElement(value) {
return true;
}
isRTL
Determines if an element is in RTL layout.
function isRTL(element) {
return false;
}
function isRTL(element) {
return false;
}
Usage
All these methods are passed to platform
platform
:
import {computePosition} from '@floating-ui/core';
computePosition(referenceEl, floatingEl, {
platform: {
// Required
getElementRects,
getDimensions,
getClippingRect,
// Optional
convertOffsetParentRelativeRectToViewportRelativeRect,
getOffsetParent,
getDocumentElement,
getClientRects,
isElement,
isRTL,
},
});
import {computePosition} from '@floating-ui/core';
computePosition(referenceEl, floatingEl, {
platform: {
// Required
getElementRects,
getDimensions,
getClippingRect,
// Optional
convertOffsetParentRelativeRectToViewportRelativeRect,
getOffsetParent,
getDocumentElement,
getClientRects,
isElement,
isRTL,
},
});