Constructors
Popper comes with two constructor functions to use.
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>) => Promise<$Shape<State>>,
|};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>,
};