Skip to content


This function computes the overflow offsets of either the reference or floating element relative to any clipping boundaries.

Almost every middleware provided by the library uses this function, making it useful for your own custom middleware.

The function takes two arguments and returns a promise:

await detectOverflow(middlewareArguments, options);


Inside your custom middleware, make your fn async and await it, passing in the middlewareArguments:

import {detectOverflow} from '@floating-ui/dom';
const middleware = {
  name: 'middleware',
  async fn(middlewareArguments) {
    const overflow = await detectOverflow(middlewareArguments);
    return {};

The returned value, overflow, is a SideObject containing side properties with numbers representing offsets.

  • A positive number means the element is overflowing the clipping boundary by that number of pixels.
  • A negative number means the element has that number of pixels left before it will overflow the clipping boundary.
  • 0 means the side lies flush with the clipping boundary.


detectOverflow() takes options as a second argument.

await detectOverflow(middlewareArguments, {
  // options


type Boundary = 'clippingAncestors' | Element | Array<Element>;

This describes the clipping element(s) that overflow will be checked relative to. The default is 'clippingAncestors', which are the overflow ancestors which will cause the element to be clipped.

await detectOverflow(middlewareArguments, {
  boundary: document.querySelector('#container'),


type RootBoundary = 'viewport' | 'document';

This describes the root boundary that the element will be checked for overflow relative to. The default is 'viewport', which is the area of the page the user can see on the screen. This is the Visual Viewport which correctly handles pinch-zooming and mobile viewports when the keyboard is open.

The other option is 'document', which is the entire page outside the viewport.

await detectOverflow(middlewareArguments, {
  rootBoundary: 'document', // 'viewport' by default


type Padding =
  | number
  | Partial<{
      top: number;
      right: number;
      bottom: number;
      left: number;

This describes the virtual padding around the boundary to check for overflow.

await detectOverflow(middlewareArguments, {
  // 5px on all sides
  padding: 5,
  // Unspecified sides are 0
  padding: {
    top: 5,
    left: 20,


type ElementContext = 'reference' | 'floating';

By default, the floating element is the one being checked for overflow.

But you can also change the context to 'reference' to instead check its overflow relative to its clipping boundary.

await detectOverflow(middlewareArguments, {
  elementContext: 'reference', // 'floating' by default


This is a boolean value which determines whether to check the alternate elementContext's boundary.

For instance, if the elementContext is 'floating', and you enable this option, then the boundary in which overflow is checked for is the 'reference''s boundary. This only applies if you are using the default 'clippingAncestors' string as the boundary.

await detectOverflow(middlewareArguments, {
  altBoundary: true, // false by default