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;
animationFrame?: boolean;
}
interface Options {
ancestorScroll?: boolean;
ancestorResize?: boolean;
elementResize?: 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
.
To support old browsers, polyfill the constructor, or disable this option and update manually when the elements resize.
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
elementResize: false,
});
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
elementResize: false,
});
animationFrame
default: false
false
Whether to update the position of the floating element on every animation frame if required.
While this option is optimized for performance, it should be used sparingly.
Aside from ensuring anchoring during an animation, it can also automatically handle layout changes where the reference element moves on the screen not as the result of scrolling or resizing.
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
animationFrame: true,
});
const cleanup = autoUpdate(referenceEl, floatingEl, update, {
animationFrame: true,
});