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: truetrue

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: truetrue

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

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

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

elementResize

default: truetrue

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

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

Testing environments

JSDOM does not support ResizeObserverResizeObserver. A polyfill or check like the following will work:

autoUpdate(referenceEl, floatingEl, update, {
  elementResize: typeof ResizeObserver === 'function',
});

autoUpdate(referenceEl, floatingEl, update, {
  elementResize: typeof ResizeObserver === 'function',
});

animationFrame

default: falsefalse

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