autoUpdate
The floating element can detach from its reference element after
the initial positioning, as computePosition()
computePosition()
is discrete
and runs only once.
To ensure the floating element remains anchored to its reference element, such as when scrolling and resizing the screen, its position needs to be continually updated when necessary.
To solve this, autoUpdate()
autoUpdate()
adds listeners that will
automatically call an update function which invokes
computePosition()
computePosition()
when necessary. Updates typically take
only ~1ms.
Only call this function when the floating element is open on the screen.
import {computePosition, autoUpdate} from '@floating-ui/dom';
// This function will get called repeatedly.
function updatePosition() {
computePosition(referenceEl, floatingEl).then(({x, y}) => {
// ...
});
}
const cleanup = autoUpdate(
referenceEl,
floatingEl,
updatePosition
);
import {computePosition, autoUpdate} from '@floating-ui/dom';
// This function will get called repeatedly.
function updatePosition() {
computePosition(referenceEl, floatingEl).then(({x, y}) => {
// ...
});
}
const cleanup = autoUpdate(
referenceEl,
floatingEl,
updatePosition
);
It returns a cleanup function that should be invoked when the floating element is removed from the screen.
// Later, when the element is removed from the screen
cleanup();
// Later, when the element is removed from the screen
cleanup();
Options
These are the options you can pass as a fourth argument to
autoUpdate()
autoUpdate()
.
interface Options {
ancestorScroll?: boolean;
ancestorResize?: boolean;
elementResize?: boolean;
layoutShift?: boolean;
animationFrame?: boolean;
}
interface Options {
ancestorScroll?: boolean;
ancestorResize?: boolean;
elementResize?: boolean;
layoutShift?: boolean;
animationFrame?: boolean;
}
ancestorScroll
default: true
true
Whether to update the position when an overflow ancestor is scrolled.
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
ancestorScroll: false,
});
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
ancestorScroll: false,
});
ancestorResize
default: true
true
Whether to update the position when an overflow ancestor is
resized. This uses the resize
resize
event.
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
ancestorResize: false,
});
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
ancestorResize: false,
});
elementResize
default: true
true
Whether to update the position when either the reference or
floating elements resized. This uses a ResizeObserver
ResizeObserver
.
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
elementResize: false,
});
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
elementResize: false,
});
layoutShift
default: true
true
Whether to update the position of the floating element if the reference element moved on the screen as the result of layout shift.
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
layoutShift: false,
});
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
layoutShift: false,
});
animationFrame
default: false
false
Whether to update the position of the floating element on every animation frame if required. While optimized for performance, it should be used sparingly in the following cases:
- The reference element is animating on the screen with
transform
s. - Ensure a nested floating element is anchored when it’s outside of ancestor floating elements’ scrolling contexts.
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
animationFrame: true,
});
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
animationFrame: true,
});