Flip

The flip modifier can change the placement of a popper when it's scheduled to overflow a given boundary.

Demo

The placement is set to bottom, but if that placement does not fit, the opposite top placement will be used.

Phase

main

Options

type Options = {
  fallbackPlacements: Array<Placement>, // [oppositePlacement]
  padding: Padding, // 0,
  boundary: Boundary, // "clippingParents"
  rootBoundary: RootBoundary, // "viewport"
  flipVariations: boolean, // true
  allowedAutoPlacements: Array<Placement>, // all supported placements
};

fallbackPlacements

If the popper has placement set to bottom, but there isn't enough space to position the popper in that direction, by default, it will change the popper placement to top. As soon as enough space is detected, the placement will be reverted to the originally defined (or preferred) one.

You can also define fallback placements by providing a list of placements to try. When no space is available on the preferred placement, the modifier will test the ones provided in the list, and use the first useful one.

createPopper(reference, popper, {
  placement: 'left',
  modifiers: [
    {
      name: 'flip',
      options: {
        fallbackPlacements: ['top', 'right'],
      },
    },
  ],
});

In the above example, the popper will be placed on left if there's enough space, if not, it will try the top placement, and if the top placement doesn't fit either, it will try to use the right placement. If even the right placement doesn't fit, it reverts back to the original placement.

padding

See padding in Detect Overflow for details.

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

boundary

See boundary in Detect Overflow for details.

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

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

rootBoundary

See rootBoundary in Detect Overflow for details.

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

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: 'flip',
      options: {
        altBoundary: true, // false by default
      },
    },
  ],
});

flipVariations

When using variation placements (e.g. top-start), the popper will attempt to flip the opposite variation if the preferred variation does not fit. This allows the popper to stay aligned to the edge of the reference element before preventOverflow has a chance to misalign it.

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

allowedAutoPlacements

The auto placement is very versatile, but sometimes you may need to make it resolve to just a user defined set of placements.
If, for example, you want auto to only ever resolve to either top or bottom, you can set allowedAutoPlacements to ['top', 'bottom'].

This feature is available starting from @popperjs/core@2.3.0

createPopper(reference, popper, {
  placement: 'auto',
  modifiers: [
    {
      name: 'flip',
      options: {
        allowedAutoPlacements: ['top', 'bottom'], // by default, all the placements are allowed
      },
    },
  ],
});

Data

This modifier has no data.