autoUpdate

import {autoUpdate} from '@floating-ui/dom';

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() adds listeners that will automatically call an update function which invokes computePosition() when necessary. Updates typically take only ~1ms.

Usage

It’s important that this function is only called/set-up when the floating element is open on the screen, and cleaned up when it’s removed. Otherwise, it can cause severe performance degradation, especially with many floating elements being created.

Call autoUpdate() only when the floating element is open or mounted:

// This function will get called repeatedly.
function updatePosition() {
  computePosition(referenceEl, floatingEl).then(({x, y}) => {
    // ...
  });
}
 
// Mount the floating element to the DOM, such as on hover
// or click.
document.body.append(floatingEl);
// Start auto updates.
const cleanup = autoUpdate(
  referenceEl,
  floatingEl,
  updatePosition,
);

Then, when the user unhovers or clicks away, unmount the floating element and ensure you call the cleanup function to stop the auto updates:

// Remove the floating element from the DOM, such as on blur
// or outside click.
floatingEl.remove();
// Stop auto updates.
cleanup();

Options

These are the options you can pass as a fourth argument to autoUpdate().

interface AutoUpdateOptions {
  ancestorScroll?: boolean;
  ancestorResize?: boolean;
  elementResize?: boolean;
  layoutShift?: boolean;
  animationFrame?: boolean;
}

ancestorScroll

default: true

Whether to update the position when an overflow ancestor is scrolled.

const cleanup = autoUpdate(referenceEl, floatingEl, update, {
  ancestorScroll: false,
});

ancestorResize

default: true

Whether to update the position when an overflow ancestor is resized. This uses the resize event.

const cleanup = autoUpdate(referenceEl, floatingEl, update, {
  ancestorResize: false,
});

elementResize

default: true

Whether to update the position when either the reference or floating elements resized. This uses a ResizeObserver.

const cleanup = autoUpdate(referenceEl, floatingEl, update, {
  elementResize: false,
});

layoutShift

default: 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,
});

animationFrame

default: 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 transforms.
• 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,
});