detectOverflow

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

A clipping boundary is one that causes child elements inside it to be clipped if they overflow it.

Visibility optimizer middleware use this function for collision detection, making it useful for your own custom middleware that perform visibility optimization.

Usage

Inside your custom middleware, make your fnfn asyncasync and awaitawait it, passing in the middleware statestate:

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

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

The returned value, overflowoverflow, is a SideObjectSideObject 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.
00 means the side lies flush with the clipping boundary.

Options

detectOverflow()detectOverflow() takes options as a second argument.

await detectOverflow(state, {
  // options
});

await detectOverflow(state, {
  // options
});

boundary

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

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

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

await detectOverflow(state, {
  boundary: document.querySelector('#container'),
});

await detectOverflow(state, {
  boundary: document.querySelector('#container'),
});

rootBoundary

type RootBoundary = 'viewport' | 'document' | Rect;

type RootBoundary = 'viewport' | 'document' | Rect;

This describes the root boundary that the element will be checked for overflow relative to. The default is 'viewport''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 string option is 'document''document', which is the entire page outside the viewport.

await detectOverflow(state, {
  rootBoundary: 'document', // 'viewport' by default
});

await detectOverflow(state, {
  rootBoundary: 'document', // 'viewport' by default
});

You may also pass a RectRect object to define a custom boundary area (relative to the viewport).

await detectOverflow(state, {
  // Layout viewport, instead of the visual viewport
  rootBoundary: {
    x: 0,
    y: 0,
    width: document.documentElement.clientWidth,
    height: document.documentElement.clientHeight,
  },
});

await detectOverflow(state, {
  // Layout viewport, instead of the visual viewport
  rootBoundary: {
    x: 0,
    y: 0,
    width: document.documentElement.clientWidth,
    height: document.documentElement.clientHeight,
  },
});

padding

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

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(state, {
  // 5px on all sides
  padding: 5,
  // Unspecified sides are 0
  padding: {
    top: 5,
    left: 20,
  },
});

await detectOverflow(state, {
  // 5px on all sides
  padding: 5,
  // Unspecified sides are 0
  padding: {
    top: 5,
    left: 20,
  },
});

elementContext

type ElementContext = 'reference' | 'floating';

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''reference' to instead check its overflow relative to its clipping boundary.

await detectOverflow(state, {
  elementContext: 'reference', // 'floating' by default
});

await detectOverflow(state, {
  elementContext: 'reference', // 'floating' by default
});

altBoundary

This is a boolean value which determines whether to check the alternate elementContextelementContext’s boundary.

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

await detectOverflow(state, {
  altBoundary: true, // false by default
});

await detectOverflow(state, {
  altBoundary: true, // false by default
});