Constructors

Popper comes with two constructor functions to use.

Don't mind tech-related ads? Consider disabling your ad-blocker to help us!
They are small and unobtrusive.
Alternatively, support us on Open Collective!

createPopper

The createPopper constructor is at the heart of Popper. It allows you to create individual popper instances (objects) with state and methods.

Imports

// esm
import { createPopper } from '@popperjs/core';

// cjs
const { createPopper } = require('@popperjs/core');

// umd
const { createPopper } = Popper;

Usage

const reference = document.querySelector('#reference');
const popper = document.querySelector('#popper');

createPopper(reference, popper, {
  // options
});

Options

type Options = {|
  placement: Placement, // "bottom"
  modifiers: Array<$Shape<Modifier<any>>>, // []
  strategy: PositioningStrategy, // "absolute",
  onFirstUpdate?: ($Shape<State>) => void, // undefined
|};

type Placement =
  | 'auto'
  | 'auto-start'
  | 'auto-end'
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'right'
  | 'right-start'
  | 'right-end'
  | 'left'
  | 'left-start'
  | 'left-end';
type Strategy = 'absolute' | 'fixed';

`placement`

Describes the preferred placement of the popper. Modifiers like flip may change the placement of the popper to make it fit better.

createPopper(reference, popper, {
  placement: 'right-start',
});

The "auto" placements will choose the side with most space.

`modifiers`

Describes the array of modifiers to add or configure. The default (full) version of Popper includes all modifiers listed in the menu.

createPopper(reference, popper, {
  modifiers: [
    {
      name: 'flip',
      enabled: false,
    },
  ],
});

See Modifiers for more information.

`strategy`

Describes the positioning strategy to use. By default, it is absolute, which in the simplest cases does not require repositioning of the popper.

If your reference element is in a fixed container, use the fixed strategy:

createPopper(reference, popper, {
  strategy: 'fixed',
});

This will prevent any jumpiness since no repositioning is needed.

Instance

createPopper returns a popper instance. This is a plain object with a state property and some methods.

Log it out in DevTools:

const instance = createPopper(reference, popper);
console.log(instance);

{
  // This is the main state object containing all of the information about the
  // popper.
  state,

  // Synchronously updates the popper instance. Use this for low-frequency
  // updates.
  forceUpdate() {},

  // Asynchronously updates the popper instance, and returns a promise. Use this
  // for high-frequency updates.
  update() {},

  // Updates the options of the instance.
  setOptions(options) {},

  // Cleans up the instance.
  destroy() {},
};

Types

type CreatePopper = (
  reference: Element | VirtualElement,
  popper: HTMLElement,
  options?: Options
) => Instance;

type Options = {|
  placement: Placement,
  modifiers: Array<$Shape<Modifier<any>>>,
  strategy: PositioningStrategy,
  onFirstUpdate?: ($Shape<State>) => void,
|};

type Instance = {|
  state: State,
  destroy: () => void,
  forceUpdate: () => void,
  update: () => Promise<$Shape<State>>,
  setOptions: (
    options: $Shape<Options> | (($Shape<Options>) => $Shape<Options>)
  ) => Promise<$Shape<State>>,
|};

`setOptions`

You can update the options of a popper instance with the setOptions method.

The method accepts either an options object or a function that takes the current options object as argument and returns the new one.

Below we set a new configuration object that replaces the current one. Note that the below example will unset all the modifiers configuration and any other custom options:

instance.setOptions({
  placement: 'bottom',
});

If, instead, we want to update the existing configuration, we can use a function to read the current options and return updated ones (available since version 2.10.0):

// Disable event listeners options without losing the rest of the set options
instance.setOptions(options => ({
  ...options,
  modifiers: [
     ...options.modifiers,
     { name: 'eventListeners', enabled: false }
  ]
}));

// Enable it back, you can also use something like Ramda#assocPath to make this terser
instance.setOptions((options) =>
  R.assocPath(['modifiers'], { name: 'eventListeners', enabled: true }, options)
);

popperGenerator

The popperGenerator constructor generates a createPopper function. This allows you to configure createPopper with the functionality you need instead of needing to pass the same defaults each time.

Imports

// esm
import { popperGenerator } from '@popperjs/core';

// cjs
const { popperGenerator } = require('@popperjs/core');

// umd
const { popperGenerator } = Popper;

Usage

const createPopper = popperGenerator({
  defaultOptions: { placement: 'top' },
  defaultModifiers: [popperOffsets, computeStyles, applyStyles, eventListeners],
});

// Now your custom `createPopper` is ready to use.

Types

type PopperGenerator = (options?: PopperGeneratorOptions) => CreatePopper;

type PopperGeneratorOptions = {
  defaultModifiers?: Array<Modifier<any>>,
  defaultOptions?: $Shape<Options>,
};

Edit this page

Tutorial

Lifecycle