Prevent Overflow

The preventOverflow modifier prevents the popper from being cut off by moving it so that it stays visible within its boundary area.

Demo

The tooltip is prevented from overflowing its clipping container, even though that won't center it anymore.

Phase

main

Options

type Options = {
  mainAxis: boolean, // true
  altAxis: boolean, // false
  padding: Padding, // 0
  boundary: Boundary, // "clippingParents"
  altBoundary: boolean, // false
  rootBoundary: RootBoundary, // "viewport"
  tether: boolean, // true
  tetherOffset: TetherOffset, // 0
};

// Below are the described relative types
type TetherOffset =
  | (({
      popper: Rect,
      reference: Rect,
      placement: Placement,
    }) => number)
  | number;

mainAxis

For top and bottom placements, this is the x-axis. For left and right placements, it is the y-axis.

By default, only this axis checked, which means if a popper with bottom placement is overflowing on the right of its boundary area, it will be moved to the left so that it doesn't get cut off.

This behavior can be disabled by setting it to false.

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'preventOverflow',
      options: {
        mainAxis: false, // true by default
      },
    },
  ],
});

altAxis

Optionally, the alternative axis check can be enabled. Keep in mind that this may cause the popper to overlap its reference element. Generally, the flip modifier is used to prevent this from happening.

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'preventOverflow',
      options: {
        altAxis: true, // false by default
      },
    },
  ],
});

padding

See padding in Detect Overflow for details.

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'preventOverflow',
      options: {
        padding: 8,
      },
    },
  ],
});

boundary

See boundary in Detect Overflow for details.

const element = document.querySelector('#parentElement');

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'preventOverflow',
      options: {
        boundary: element,
      },
    },
  ],
});

altBoundary

This will check the reference's boundary context (clippingParents) instead of the popper's, effectively replicating the scrollParent boundary from Popper v1. See altBoundary in Detect Overflow for details.

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'preventOverflow',
      options: {
        altBoundary: true, // false by default
      },
    },
  ],
});

rootBoundary

See rootBoundary in Detect Overflow for details.

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'preventOverflow',
      options: {
        rootBoundary: 'document',
      },
    },
  ],
});

tether

While trying to keep the popper element within its overflow area is usually desired, we likely don't want to reach the point where the reference and popper elements are not touching (or "tethered") to each other at all, since that would make it difficult for the user to understand where the popper originated from.

The default behavior is to avoid this situation by allowing the popper to overflow once the opposite edges of the reference element and popper element are aligned (i.e. right before they would appear to be detached).

This behavior can be disabled by setting it to false:

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'preventOverflow',
      options: {
        tether: false, // true by default
      },
    },
  ],
});

tetherOffset

When tether is enabled, you can customize its behavior by providing an offset to be used during the tether calculations. Setting the offset to a positive number will make the tether behavior activate earlier, while setting it negative will do the opposite.

The tetherOffset option can also take a function, this will enable you to read some useful data, such as the popper and reference measures, or the current popper placement:

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'preventOverflow',
      options: {
        tetherOffset: ({ popper, reference, placement }) => popper.width / 2,
      },
    },
  ],
});

Data

// Describes how much the Popper has been moved from its desired position so
// that it doesn't overflow
type Data = {
  x: number,
  y: number,
};