Skip to content

popper-documentation.md

Latest commit

 

History

History
1419 lines (1048 loc) · 50.8 KB

popper-documentation.md

File metadata and controls

1419 lines (1048 loc) · 50.8 KB
Raw

Classes

Popper

Members

dataObject

The dataObject is an object containing all the informations used by Popper.js this object get 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

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

onUpdateCallback : function
onCreateCallback : function

Popper

Kind: global class

new Popper(reference, popper, options)

Create a new Popper.js instance

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

Param Type Description
reference HTMLElement | referenceObject The reference element used to position the popper
popper HTMLElement The HTML element used as popper.
options Object Your custom options to override the ones defined in DEFAULTS

Popper.DEFAULTS : Object

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

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

Kind: static property of Popper

DEFAULTS.placement

Popper's placement

Kind: static property of DEFAULTS
Properties

Name Type Default
placement placements 'bottom'

DEFAULTS.eventsEnabled

Whether events (resize, scroll) are initially enabled

Kind: static property of DEFAULTS
Properties

Name Type Default
eventsEnabled Boolean true

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

Name Type Default
removeOnDestroy Boolean false

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

Type
modifiers

DEFAULTS.onCreate()

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

Kind: static method of DEFAULTS
Properties

Type
onCreateCallback

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, is set to no-op.
Access Popper.js instance with data.instance.

Kind: static method of DEFAULTS
Properties

Type
onUpdateCallback

Popper.Utils : Object

Deprecated

Collection of utilities useful when writing custom modifiers. Starting from version 1.7, this method is available only if you include popper-utils.js before popper.js.

DEPRECATION: This way to access PopperUtils is deprecated and will be removed in v2! Use the PopperUtils module directly instead.

Kind: static property of Popper

Utils.isNative(fn) ⇒ Boolean

Determine if a function is implemented natively (as opposed to a polyfill).

Kind: static method of Utils

Param Type Description
fn function | undefined the function to check

Utils.debounce(fn) ⇒ function

Create a debounced version of a method, that's asynchronously deferred but called in the minimum time possible.

Kind: static method of Utils

Param Type
fn function

Utils.isNumeric(input) ⇒ Boolean

Tells if a given input is a number

Kind: static method of Utils

Param Type Description
input * to check

Utils.setStyles(element, styles)

Set the style to the given popper

Kind: static method of Utils

Param Type Description
element Element Element to apply the style to
styles Object Object with a list of properties and values which will be applied to the element

Utils.isFunction(functionToCheck) ⇒ Boolean

Check if the given variable is a function

Kind: static method of Utils
Returns: Boolean - answer to: is a function?

Param Type Description
functionToCheck Any variable to check

Utils.getStyleComputedProperty(element, property)

Get CSS computed property of the given element

Kind: static method of Utils

Param Type
element Eement
property String

Utils.getParentNode(element) ⇒ Element

Returns the parentNode or the host of the element

Kind: static method of Utils
Returns: Element - parent

Param Type
element Element

Utils.getScrollParent(element) ⇒ Element

Returns the scrolling parent of the given element

Kind: static method of Utils
Returns: Element - scroll parent

Param Type
element Element

Utils.getRoot(node) ⇒ Element

Finds the root node (document, shadowDOM root) of the given element

Kind: static method of Utils
Returns: Element - root node

Param Type
node Element

Utils.getOffsetParent(element) ⇒ Element

Returns the offset parent of the given element

Kind: static method of Utils
Returns: Element - offset parent

Param Type
element Element

Utils.findCommonOffsetParent(element1, element2) ⇒ Element

Finds the offset parent common to the two provided nodes

Kind: static method of Utils
Returns: Element - common offset parent

Param Type
element1 Element
element2 Element

Utils.getScroll(element, side) ⇒ number

Gets the scroll value of the given element in the given side (top and left)

Kind: static method of Utils
Returns: number - amount of scrolled pixels

Param Type Default Description
element Element
side String top top or left

Utils.getClientRect(offsets) ⇒ Object

Given element offsets, generate an output similar to getBoundingClientRect

Kind: static method of Utils
Returns: Object - ClientRect like output

Param Type
offsets Object

Utils.isIE10() ⇒ Boolean

Tells if you are running Internet Explorer 10

Kind: static method of Utils
Returns: Boolean - isIE10

Utils.getBoundingClientRect(element) ⇒ Object

Get bounding client rect of given element

Kind: static method of Utils
Returns: Object - client rect

Param Type
element HTMLElement

Utils.isFixed(element, customContainer) ⇒ Boolean

Check if the given element is fixed or is inside a fixed parent

Kind: static method of Utils
Returns: Boolean - answer to "isFixed?"

Param Type
element Element
customContainer Element

Utils.getBoundaries(popper, reference, padding, boundariesElement) ⇒ Object

Computed the boundaries limits and return them

Kind: static method of Utils
Returns: Object - Coordinates of the boundaries

Param Type Description
popper HTMLElement
reference HTMLElement
padding number
boundariesElement HTMLElement Element used to define the boundaries

Utils.computeAutoPlacement(data, options) ⇒ Object

Utility used to transform the auto placement to the placement with more available space.

Kind: static method of Utils
Returns: Object - The data object, properly modified

Param Type Description
data Object The data object generated by update method
options Object Modifiers configuration and options

Utils.getReferenceOffsets(state, popper, reference) ⇒ Object

Get offsets to the reference element

Kind: static method of Utils
Returns: Object - An object containing the offsets which will be applied to the popper

Param Type Description
state Object
popper Element the popper element
reference Element the reference element (the popper will be relative to this)

Utils.getOuterSizes(element) ⇒ Object

Get the outer sizes of the given element (offset size + margins)

Kind: static method of Utils
Returns: Object - object containing width and height properties

Param Type
element Element

Utils.getOppositePlacement(placement) ⇒ String

Get the opposite placement of the given one

Kind: static method of Utils
Returns: String - flipped placement

Param Type
placement String

Utils.getPopperOffsets(position, popper, referenceOffsets, placement) ⇒ Object

Get offsets to the popper

Kind: static method of Utils
Returns: Object - popperOffsets - An object containing the offsets which will be applied to the popper

Param Type Description
position Object CSS position the Popper will get applied
popper HTMLElement the popper element
referenceOffsets Object the reference offsets (the popper will be relative to this)
placement String one of the valid placement options

Utils.find(arr, prop, value) ⇒

Mimics the find method of Array

Kind: static method of Utils
Returns: index or -1

Param Type
arr Array
prop
value

Utils.findIndex(arr, prop, value) ⇒

Return the index of the matching object

Kind: static method of Utils
Returns: index or -1

Param Type
arr Array
prop
value

Utils.runModifiers(data, modifiers, ends) ⇒ dataObject

Loop trough the list of modifiers and run them in order, each of them will then edit the data object.

Kind: static method of Utils

Param Type Description
data dataObject
modifiers Array
ends String Optional modifier name used as stopper

Utils.isModifierEnabled() ⇒ Boolean

Helper used to know if the given modifier is enabled.

Kind: static method of Utils

Utils.getSupportedPropertyName(property) ⇒ String

Get the prefixed supported property name

Kind: static method of Utils
Returns: String - prefixed property (camelCase)

Param Type Description
property String (camelCase)

Utils.setAttributes(element, styles)

Set the attributes to the given popper

Kind: static method of Utils

Param Type Description
element Element Element to apply the attributes to
styles Object Object with a list of properties and values which will be applied to the element

Utils.isModifierRequired(modifiers, requestingName, requestedName) ⇒ Boolean

Helper used to know if the given modifier depends from another one.
It checks if the needed modifier is listed and enabled.

Kind: static method of Utils

Param Type Description
modifiers Array list of modifiers
requestingName String name of requesting modifier
requestedName String name of requested modifier

Utils.getOppositeVariation(placement) ⇒ String

Get the opposite placement variation of the given one

Kind: static method of Utils
Returns: String - flipped placement variation

Param Type Description
placement String variation

Utils.clockwise(placement, counter) ⇒ Array

Given an initial placement, returns all the subsequent placements clockwise (or counter-clockwise).

Kind: static method of Utils
Returns: Array - placements including their variations

Param Type Default Description
placement String A valid placement (it accepts variations)
counter Boolean false Set to true to walk the placements counterclockwise

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-right (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()

Destroy 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()

Schedule 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 informations used by Popper.js this object get passed to modifiers and to the onCreate and onUpdate callbacks.

Kind: global variable
Properties

Name Type Description
data.instance Object The Popper.js instance
data.placement String Placement applied to popper
data.originalPlacement String Placement originally defined on init
data.flipped Boolean True if popper has been flipped by flip modifier
data.hide Boolean True if the reference element is out of boundaries, useful to know when to hide the popper.
data.arrowElement HTMLElement Node used as arrow by arrow modifier
data.styles Object Any CSS property defined here will be applied to the popper, it expects the JavaScript nomenclature (eg. marginBottom)
data.boundaries Object Offsets of the popper boundaries
data.offsets Object The measurements of popper, reference and arrow elements.
data.offsets.popper Object top, left, width, height values
data.offsets.reference Object top, left, width, height values
data.offsets.arro Object top and left offsets, only one of them will be different from 0

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

Name Type Description
data.getBoundingClientRect function A function that returns a set of coordinates compatible with the native getBoundingClientRect method.
data.clientWidth number An ES6 getter that will return the width of the virtual reference element.
data.clientHeight number An ES6 getter that will return the height of the virtual reference element.

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~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

Kind: static property of shift
Properties

Name Type Default Description
order number 100 Index used to define the order of execution

shift.enabled

Kind: static property of shift
Properties

Name Type Default Description
enabled Boolean true Whether the modifier is enabled or not

shift.fn

Kind: static property of shift
Properties

Type
ModifierFn

modifiers~offset

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

It accepts the following units:

  • px or unitless, 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%'

Kind: inner property of modifiers

offset.order

Kind: static property of offset
Properties

Name Type Default Description
order number 200 Index used to define the order of execution

offset.enabled

Kind: static property of offset
Properties

Name Type Default Description
enabled Boolean true Whether the modifier is enabled or not

offset.fn

Kind: static property of offset
Properties

Type
ModifierFn

offset.offset

Kind: static property of offset
Properties

Name Type Default Description
offset Number | String 0 The offset value as described in the modifier description

modifiers~preventOverflow

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

An 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

Kind: static property of preventOverflow
Properties

Name Type Default Description
order number 300 Index used to define the order of execution

preventOverflow.enabled

Kind: static property of preventOverflow
Properties

Name Type Default Description
enabled Boolean true Whether the modifier is enabled or not

preventOverflow.fn

Kind: static property of preventOverflow
Properties

Type
ModifierFn

preventOverflow.priority

Kind: static property of preventOverflow
Properties

Name Type Default Description
priority Array ['left', 'right', 'top', 'bottom'] Popper will try to prevent overflow following these priorities by default, then, it could overflow on the left and on top of the boundariesElement

preventOverflow.padding

Kind: static property of preventOverflow
Properties

Name Type Default Description
padding number 5 Amount of pixel used to define a minimum distance between the boundaries and the popper this makes sure the popper has always a little padding between the edges of its container

preventOverflow.boundariesElement

Kind: static property of preventOverflow
Properties

Name Type Default Description
boundariesElement String | HTMLElement 'scrollParent' Boundaries used by the modifier, can be scrollParent, window, viewport or any DOM element.

modifiers~keepTogether

Modifier used to make sure the reference and its popper stay near eachothers without leaving any gap between the two. Expecially useful when the arrow is enabled and you want to assure it to point 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

Kind: static property of keepTogether
Properties

Name Type Default Description
order number 400 Index used to define the order of execution

keepTogether.enabled

Kind: static property of keepTogether
Properties

Name Type Default Description
enabled Boolean true Whether the modifier is enabled or not

keepTogether.fn

Kind: static property of keepTogether
Properties

Type
ModifierFn

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 conjuction are needed.

It has no effect if no arrowElement is provided.

Kind: inner property of modifiers

arrow.order

Kind: static property of arrow
Properties

Name Type Default Description
order number 500 Index used to define the order of execution

arrow.enabled

Kind: static property of arrow
Properties

Name Type Default Description
enabled Boolean true Whether the modifier is enabled or not

arrow.fn

Kind: static property of arrow
Properties

Type
ModifierFn

arrow.element

Kind: static property of arrow
Properties

Name Type Default Description
element String | HTMLElement '[x-arrow]' Selector or node used as arrow

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

Kind: static property of flip
Properties

Name Type Default Description
order number 600 Index used to define the order of execution

flip.enabled

Kind: static property of flip
Properties

Name Type Default Description
enabled Boolean true Whether the modifier is enabled or not

flip.fn

Kind: static property of flip
Properties

Type
ModifierFn

flip.behavior

Kind: static property of flip
Properties

Name Type Default Description
behavior String | Array 'flip' The behavior used to change the popper's placement. It can be one of flip, clockwise, counterclockwise or an array with a list of valid placements (with optional variations).

flip.padding

Kind: static property of flip
Properties

Name Type Default Description
padding number 5 The popper will flip if it hits the edges of the boundariesElement

flip.boundariesElement

Kind: static property of flip
Properties

Name Type Default Description
boundariesElement String | HTMLElement 'viewport' The element which will define the boundaries of the popper position, the popper will never be placed outside of the defined boundaries (except if keepTogether is enabled)

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

Kind: static property of inner
Properties

Name Type Default Description
order number 700 Index used to define the order of execution

inner.enabled

Kind: static property of inner
Properties

Name Type Default Description
enabled Boolean false Whether the modifier is enabled or not

inner.fn

Kind: static property of inner
Properties

Type
ModifierFn

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

Kind: static property of hide
Properties

Name Type Default Description
order number 800 Index used to define the order of execution

hide.enabled

Kind: static property of hide
Properties

Name Type Default Description
enabled Boolean true Whether the modifier is enabled or not

hide.fn

Kind: static property of hide
Properties

Type
ModifierFn

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.

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

Kind: inner property of modifiers

applyStyle.order

Kind: static property of applyStyle
Properties

Name Type Default Description
order number 900 Index used to define the order of execution

applyStyle.enabled

Kind: static property of applyStyle
Properties

Name Type Default Description
enabled Boolean true Whether the modifier is enabled or not

applyStyle.fn

Kind: static property of applyStyle
Properties

Type
ModifierFn

applyStyle.onLoad

Kind: static property of applyStyle
Properties

Type
function

applyStyle.gpuAcceleration

Kind: static property of applyStyle
Properties

Name Type Default Description
gpuAcceleration Boolean true If true, it uses the CSS 3d transformation to position the popper. Otherwise, it will use the top and left properties.

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

Param Type Description
data dataObject The data object generated by update method
options Object Modifiers configuration and options

onUpdateCallback : function

Kind: global typedef

Param Type
data dataObject

onCreateCallback : function

Kind: global typedef

Param Type
data dataObject