Popper.js (v1.x)

This page covers the API reference and documentation of Popper 1 (popper.js on npm).

This page is here to help consumers who haven't migrated yet to the most recent version, for the latest version documentation click here.

Classes

Popper

Members

dataObject

The dataObject is an object containing all the information used by Popper.js. This object is passed to modifiers and to the onCreate and onUpdate callbacks.

referenceObject

The referenceObject is an object that provides an interface compatible with Popper.js and lets you use it as replacement of a real DOM node.
You can use this method to position a popper relatively to a set of coordinates in case you don't have a DOM node to use as reference.

new Popper(referenceObject, popperNode);

NB: This feature isn't supported in Internet Explorer 10.

Objects

modifiers : object

Modifiers are plugins used to alter the behavior of your poppers.
Popper.js uses a set of 9 modifiers to provide all the basic functionalities needed by the library.

Usually you don't want to override the order, fn and onLoad props. All the other properties are configurations that could be tweaked.

Functions

getWindow(element) ⇒ Window

Get the window associated with the element

ModifierFn(data, options) ⇒ dataObject

Modifier function, each modifier can have a function of this type assigned to its fn property.
These functions will be called on each update, this means that you must make sure they are performant enough to avoid performance bottlenecks.

Typedefs

onUpdate : function

onCreate : function

Popper

Kind: global class

• Popper
  • new Popper(reference, popper, options)
  • .Defaults : Object
    • .placement
    • .positionFixed
    • .eventsEnabled
    • .removeOnDestroy
    • .modifiers
    • .onCreate()
    • .onUpdate()
  • .placements : enum
  • .update()
  • .destroy()
  • .enableEventListeners()
  • .disableEventListeners()
  • .scheduleUpdate()

new Popper(reference, popper, options)

Creates a new Popper.js instance.

Returns: Object - instance - The generated Popper.js instance

Popper.Defaults : Object

Default options provided to Popper.js constructor.
These can be overridden using the options argument of Popper.js.
To override an option, simply pass an object with the same structure of the options object, as the 3rd argument. For example:

new Popper(ref, pop, {
  modifiers: {
    preventOverflow: { enabled: false },
  },
});

Kind: static property of Popper

• .Defaults : Object
  • .placement
  • .positionFixed
  • .eventsEnabled
  • .removeOnDestroy
  • .modifiers
  • .onCreate()
  • .onUpdate()

Defaults.placement

Popper's placement.

Kind: static property of Defaults
Properties

Defaults.positionFixed

Set this to true if you want popper to position it self in 'fixed' mode

Kind: static property of Defaults
Properties

Defaults.eventsEnabled

Whether events (resize, scroll) are initially enabled.

Kind: static property of Defaults
Properties

Defaults.removeOnDestroy

Set to true if you want to automatically remove the popper when you call the destroy method.

Kind: static property of Defaults
Properties

Defaults.modifiers

List of modifiers used to modify the offsets before they are applied to the popper. They provide most of the functionalities of Popper.js.

Kind: static property of Defaults
Properties

Defaults.onCreate()

Callback called when the popper is created.
By default, it is set to no-op.
Access Popper.js instance with data.instance.

Kind: static method of Defaults
Properties

Defaults.onUpdate()

Callback called when the popper is updated. This callback is not called on the initialization/creation of the popper, but only on subsequent updates.
By default, it is set to no-op.
Access Popper.js instance with data.instance.

Kind: static method of Defaults
Properties

Popper.placements : enum

List of accepted placements to use as values of the placement option.
Valid placements are:

• auto
• top
• right
• bottom
• left

Each placement can have a variation from this list:

• -start
• -end

Variations are interpreted easily if you think of them as the left to right written languages. Horizontally (top and bottom), start is left and end is right.
Vertically (left and right), start is top and end is bottom.

Some valid examples are:

• top-end (on top of reference, right aligned)
• right-start (on right of reference, top aligned)
• bottom (on bottom, centered)
• auto-end (on the side with more space available, alignment depends by placement)

Kind: static enum of Popper
Read only: true

Popper.update()

Updates the position of the popper, computing the new offsets and applying the new style.
Prefer scheduleUpdate over update because of performance reasons.

Kind: static method of Popper

Popper.destroy()

Destroys the popper.

Kind: static method of Popper

Popper.enableEventListeners()

It will add resize/scroll events and start recalculating position of the popper element when they are triggered.

Kind: static method of Popper

Popper.disableEventListeners()

It will remove resize/scroll events and won't recalculate popper position when they are triggered. It also won't trigger onUpdate callback anymore, unless you call update method manually.

Kind: static method of Popper

Popper.scheduleUpdate()

Schedules an update. It will run on the next UI update available.

Kind: static method of Popper

dataObject

The dataObject is an object containing all the information used by Popper.js. This object is passed to modifiers and to the onCreate and onUpdate callbacks.

Kind: global variable
Properties

referenceObject

The referenceObject is an object that provides an interface compatible with Popper.js and lets you use it as replacement of a real DOM node.
You can use this method to position a popper relatively to a set of coordinates in case you don't have a DOM node to use as reference.

new Popper(referenceObject, popperNode);

NB: This feature isn't supported in Internet Explorer 10.

Kind: global variable
Properties

modifiers : object

Modifiers are plugins used to alter the behavior of your poppers.
Popper.js uses a set of 9 modifiers to provide all the basic functionalities needed by the library.

Usually you don't want to override the order, fn and onLoad props. All the other properties are configurations that could be tweaked.

Kind: global namespace

• modifiers : object
  • ~shift
    • .order
    • .enabled
    • .fn
  • ~offset
    • .order
    • .enabled
    • .fn
    • .offset
  • ~preventOverflow
    • .order
    • .enabled
    • .fn
    • .priority
    • .padding
    • .boundariesElement
  • ~keepTogether
    • .order
    • .enabled
    • .fn
  • ~arrow
    • .order
    • .enabled
    • .fn
    • .element
  • ~flip
    • .order
    • .enabled
    • .fn
    • .behavior
    • .padding
    • .boundariesElement
    • .flipVariations
    • .flipVariationsByContent
  • ~inner
    • .order
    • .enabled
    • .fn
  • ~hide
    • .order
    • .enabled
    • .fn
  • ~computeStyle
    • .order
    • .enabled
    • .fn
    • .gpuAcceleration
    • .x
    • .y
  • ~applyStyle
    • .order
    • .enabled
    • .fn
    • .onLoad
    • .gpuAcceleration

modifiers~shift

Modifier used to shift the popper on the start or end of its reference element.
It will read the variation of the placement property.
It can be one either -end or -start.

Kind: inner property of modifiers

• ~shift
  • .order
  • .enabled
  • .fn

shift.order

Kind: static property of shift
Properties

shift.enabled

Kind: static property of shift
Properties

shift.fn

Kind: static property of shift
Properties

modifiers~offset

The offset modifier can shift your popper on both its axis.

It accepts the following units:

• px or unit-less, interpreted as pixels
• % or %r, percentage relative to the length of the reference element
• %p, percentage relative to the length of the popper element
• vw, CSS viewport width unit
• vh, CSS viewport height unit

For length is intended the main axis relative to the placement of the popper.
This means that if the placement is top or bottom, the length will be the width. In case of left or right, it will be the height.

You can provide a single value (as Number or String), or a pair of values as String divided by a comma or one (or more) white spaces.
The latter is a deprecated method because it leads to confusion and will be removed in v2.
Additionally, it accepts additions and subtractions between different units. Note that multiplications and divisions aren't supported.

Valid examples are:

10
'10%'
'10, 10'
'10%, 10'
'10 + 10%'
'10 - 5vh + 3%'
'-10px + 5vh, 5px - 6%'

NB: If you desire to apply offsets to your poppers in a way that may make them overlap with their reference element, unfortunately, you will have to disable the flip modifier. You can read more on this at this issue.

Kind: inner property of modifiers

• ~offset
  • .order
  • .enabled
  • .fn
  • .offset

offset.order

Kind: static property of offset
Properties

offset.enabled

Kind: static property of offset
Properties

offset.fn

Kind: static property of offset
Properties

offset.offset

Kind: static property of offset
Properties

modifiers~preventOverflow

Modifier used to prevent the popper from being positioned outside the boundary.

A scenario exists where the reference itself is not within the boundaries.
We can say it has "escaped the boundaries" — or just "escaped".
In this case we need to decide whether the popper should either:

• detach from the reference and remain "trapped" in the boundaries, or
• if it should ignore the boundary and "escape with its reference"

When escapeWithReference is set totrue and reference is completely outside its boundaries, the popper will overflow (or completely leave) the boundaries in order to remain attached to the edge of the reference.

Kind: inner property of modifiers

• ~preventOverflow
  • .order
  • .enabled
  • .fn
  • .priority
  • .padding
  • .boundariesElement

preventOverflow.order

Kind: static property of preventOverflow
Properties

preventOverflow.enabled

Kind: static property of preventOverflow
Properties

preventOverflow.fn

Kind: static property of preventOverflow
Properties

preventOverflow.priority

Kind: static property of preventOverflow
Properties

preventOverflow.padding

Kind: static property of preventOverflow
Properties

preventOverflow.boundariesElement

Kind: static property of preventOverflow
Properties

modifiers~keepTogether

Modifier used to make sure the reference and its popper stay near each other without leaving any gap between the two. Especially useful when the arrow is enabled and you want to ensure that it points to its reference element. It cares only about the first axis. You can still have poppers with margin between the popper and its reference element.

Kind: inner property of modifiers

• ~keepTogether
  • .order
  • .enabled
  • .fn

keepTogether.order

Kind: static property of keepTogether
Properties

keepTogether.enabled

Kind: static property of keepTogether
Properties

keepTogether.fn

Kind: static property of keepTogether
Properties

modifiers~arrow

This modifier is used to move the arrowElement of the popper to make sure it is positioned between the reference element and its popper element. It will read the outer size of the arrowElement node to detect how many pixels of conjunction are needed.

It has no effect if no arrowElement is provided.

Kind: inner property of modifiers

• ~arrow
  • .order
  • .enabled
  • .fn
  • .element

arrow.order

Kind: static property of arrow
Properties

arrow.enabled

Kind: static property of arrow
Properties

arrow.fn

Kind: static property of arrow
Properties

arrow.element

Kind: static property of arrow
Properties

modifiers~flip

Modifier used to flip the popper's placement when it starts to overlap its reference element.

Requires the preventOverflow modifier before it in order to work.

NOTE: this modifier will interrupt the current update cycle and will restart it if it detects the need to flip the placement.

Kind: inner property of modifiers

• ~flip
  • .order
  • .enabled
  • .fn
  • .behavior
  • .padding
  • .boundariesElement
  • .flipVariations
  • .flipVariationsByContent

flip.order

Kind: static property of flip
Properties

flip.enabled

Kind: static property of flip
Properties

flip.fn

Kind: static property of flip
Properties

flip.behavior

Kind: static property of flip
Properties

flip.padding

Kind: static property of flip
Properties

flip.boundariesElement

Kind: static property of flip
Properties

flip.flipVariations

Kind: static property of flip
Properties

flip.flipVariationsByContent

Kind: static property of flip
Properties

modifiers~inner

Modifier used to make the popper flow toward the inner of the reference element. By default, when this modifier is disabled, the popper will be placed outside the reference element.

Kind: inner property of modifiers

• ~inner
  • .order
  • .enabled
  • .fn

inner.order

Kind: static property of inner
Properties

inner.enabled

Kind: static property of inner
Properties

inner.fn

Kind: static property of inner
Properties

modifiers~hide

Modifier used to hide the popper when its reference element is outside of the popper boundaries. It will set a x-out-of-boundaries attribute which can be used to hide with a CSS selector the popper when its reference is out of boundaries.

Requires the preventOverflow modifier before it in order to work.

Kind: inner property of modifiers

• ~hide
  • .order
  • .enabled
  • .fn

hide.order

Kind: static property of hide
Properties

hide.enabled

Kind: static property of hide
Properties

hide.fn

Kind: static property of hide
Properties

modifiers~computeStyle

Computes the style that will be applied to the popper element to gets properly positioned.

Note that this modifier will not touch the DOM, it just prepares the styles so that applyStyle modifier can apply it. This separation is useful in case you need to replace applyStyle with a custom implementation.

This modifier has 850 as order value to maintain backward compatibility with previous versions of Popper.js. Expect the modifiers ordering method to change in future major versions of the library.

Kind: inner property of modifiers

• ~computeStyle
  • .order
  • .enabled
  • .fn
  • .gpuAcceleration
  • .x
  • .y

computeStyle.order

Kind: static property of computeStyle
Properties

computeStyle.enabled

Kind: static property of computeStyle
Properties

computeStyle.fn

Kind: static property of computeStyle
Properties

computeStyle.gpuAcceleration

Kind: static property of computeStyle
Properties

computeStyle.x

Kind: static property of computeStyle
Properties

computeStyle.y

Kind: static property of computeStyle
Properties

modifiers~applyStyle

Applies the computed styles to the popper element.

All the DOM manipulations are limited to this modifier. This is useful in case you want to integrate Popper.js inside a framework or view library and you want to delegate all the DOM manipulations to it.

Note that if you disable this modifier, you must make sure the popper element has its position set to absolute before Popper.js can do its work!

Just disable this modifier and define your own to achieve the desired effect.

Kind: inner property of modifiers

• ~applyStyle
  • .order
  • .enabled
  • .fn
  • .onLoad
  • .gpuAcceleration

applyStyle.order

Kind: static property of applyStyle
Properties

applyStyle.enabled

Kind: static property of applyStyle
Properties

applyStyle.fn

Kind: static property of applyStyle
Properties

applyStyle.onLoad

Kind: static property of applyStyle
Properties

applyStyle.gpuAcceleration

Deprecated

Kind: static property of applyStyle
Properties

getWindow(element) ⇒ Window

Get the window associated with the element

Kind: global function

ModifierFn(data, options) ⇒ dataObject

Modifier function, each modifier can have a function of this type assigned to its fn property.
These functions will be called on each update, this means that you must make sure they are performant enough to avoid performance bottlenecks.

Kind: global function
Returns: dataObject - The data object, properly modified

onUpdate : function

Kind: global typedef

onCreate : function

Kind: global typedef