Skip to content

Latest commit

 

History

History
778 lines (576 loc) · 36.1 KB

popper-documentation.md

File metadata and controls

778 lines (576 loc) · 36.1 KB

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.

Objects

Modifiers ⇒ Object

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

Each modifier is an object containing several properties listed below.

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 Default Description
reference HTMLElement The reference element used to position the popper
popper HTMLElement The HTML element used as popper.
options Object
options.placement String bottom Placement of the popper accepted values: top(-start, -end), right(-start, -end), bottom(-start, -end), left(-start, -end)
options.eventsEnabled Boolean true Whether events (resize, scroll) are initially enabled
options.gpuAcceleration Boolean true When this property is set to true, the popper position will be applied using CSS3 translate3d, allowing the browser to use the GPU to accelerate the rendering. If set to false, the popper will be placed using top and left properties, not using the GPU.
options.removeOnDestroy Boolean false Set to true if you want to automatically remove the popper when you call the destroy method.
options.modifiers Object List of functions used to modify the data before they are applied to the popper (see source code for default values)
options.modifiers.arrow Object Arrow modifier configuration
options.modifiers.arrow.element String | HTMLElement '[x-arrow]' The DOM Node used as arrow for the popper, or a CSS selector used to get the DOM node. It must be child of its parent Popper. Popper.js will apply to the given element the style required to align the arrow with its reference element. By default, it will look for a child node of the popper with the x-arrow attribute.
options.modifiers.offset Object Offset modifier configuration
options.modifiers.offset.offset Number 0 Amount of pixels the popper will be shifted (can be negative).
options.modifiers.preventOverflow Object PreventOverflow modifier configuration
[options.modifiers.preventOverflow.priority] Array ['left', 'right', 'top', 'bottom'] Priority used when Popper.js tries to avoid overflows from the boundaries, they will be checked in order, this means that the last one will never overflow
options.modifiers.preventOverflow.boundariesElement String | HTMLElement 'scrollParent' Boundaries used by the modifier, can be scrollParent, window, viewport or any DOM element.
options.modifiers.preventOverflow.padding Number 5 Amount of pixels 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.
options.modifiers.flip Object Flip modifier configuration
options.modifiers.flip.behavior String | Array 'flip' The behavior used by the flip modifier to change the placement of the popper when the latter is trying to overlap its reference element. Defining flip as value, the placement will be flipped on its axis (right - left, top - bottom). You can even pass an array of placements (eg: ['right', 'left', 'top'] ) to manually specify how alter the placement when a flip is needed. (eg. in the above example, it would first flip from right to left, then, if even in its new placement, the popper is overlapping its reference element, it will be moved to top)
options.modifiers.flip.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)
options.modifiers.inner Object Inner modifier configuration
options.modifiers.inner.enabled Number false Set to true to make the popper flow toward the inner of the reference element.
options.modifiers.flip.padding Number 5 Amount of pixels used to define a minimum distance between the boundaries and the popper this makes sure the popper will flip before it touches the edge of the boundaries, making it have always a little padding between the edges of its container.
options.onCreate createCallback onCreate callback Function called after the Popper has been instantiated.
options.onUpdate updateCallback onUpdate callback Function called on subsequent updates of Popper.

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: instance method of Popper

popper.destroy()

Destroy the popper

Kind: instance method of Popper

popper.enableEventListeners()

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

Kind: instance 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: instance method of Popper

Popper.Utils : object

Kind: static namespace of Popper

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.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.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.getPosition(element) ⇒ String

Helper used to get the position which will be applied to the popper

Kind: static method of Utils
Returns: String - position

Param Type Description
element HTMLElement popper element

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.getOffsetRectRelativeToCustomParent(element, parent) ⇒ Object

Given an element and one of its parents, return the offset

Kind: static method of Utils
Returns: Object - rect

Param Type
element HTMLElement
parent HTMLElement

Utils.getOffsetRect(element) ⇒ Object

Get the position of the given element, relative to its offset parent

Kind: static method of Utils
Returns: Object - position - Coordinates of the element and its scrollTop

Param Type
element Element

Utils.getBoundaries(data, padding, boundariesElement) ⇒ Object

Computed the boundaries limits and return them

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

Param Type Description
data Object Object containing the property "offsets" generated by _getOffsets
padding Number Boundaries padding
boundariesElement Element 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.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.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.getClientRect(popperOffsets) ⇒ Object

Given the popper offsets, generate an output similar to getBoundingClientRect

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

Param Type
popperOffsets Object

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.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.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.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 * variable to check

Utils.isModifierEnabled() ⇒ Boolean

Helper used to know if the given modifier is enabled.

Kind: static method of Utils

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.isNumeric(input) ⇒ Boolean

Tells if a given input is a number

Kind: static method of Utils

Param Type Description
input * to check

Utils.isTransformed(element) ⇒ Boolean

Check if the given element has transforms applied to itself or a parent

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

Param Type
element Element

Utils.runModifiers(data, modifiers, ends)

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
data Object
modifiers Array
ends function

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

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

Modifiers ⇒ Object

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

Each modifier is an object containing several properties listed below.

Kind: global namespace
Returns: Object - data - Each modifier must return the modified data object.

Param Type Description
modifier Object Modifier descriptor
modifier.order Integer The order property defines the execution order of the modifiers. The built-in modifiers have orders with a gap of 100 units in between, this allows you to inject additional modifiers between the existing ones without having to redefine the order of all of them. The modifiers are executed starting from the one with the lowest order.
modifier.enabled Boolean When true, the modifier will be used.
modifier.function modifier Modifier function.
modifier.onLoad Modifiers~onLoad Function executed on popper initalization

Modifiers.applyStyle(data, options) ⇒ Object

Apply the computed styles to the popper element

Kind: static method of Modifiers
Returns: Object - The same data object

Param Type Description
data Object The data object generated by update method
data.styles Object List of style properties - values to apply to popper element
data.attributes Object List of attribute properties - values to apply to popper element
options Object Modifiers configuration and options

Modifiers.arrow(data, options) ⇒ Object

Modifier used to move the arrowElements on the edge of the popper to make sure them are always between the popper and the reference element It will use the CSS outer size of the arrowElement element to know how many pixels of conjuction are needed

Kind: static method of Modifiers
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

Modifiers.flip(data, options) ⇒ Object

Modifier used to flip the placement of the popper when the latter is starting overlapping its reference element. Requires the preventOverflow modifier before it in order to work. NOTE: data.instance modifier will run all its previous modifiers everytime it tries to flip the popper!

Kind: static method of Modifiers
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

Modifiers.keepTogether(data, options) ⇒ Object

Modifier used to make sure the popper is always near 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: static method of Modifiers
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

Modifiers.offset(data, options) ⇒ Object

Modifier used to add an offset to the popper, useful if you more granularity positioning your popper. The offsets will shift the popper on the side of its reference element.

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

Param Type Default Description
data Object The data object generated by update method
options Object Modifiers configuration and options
options.offset Number | String 0 Basic usage allows a number used to nudge the popper by the given amount of pixels. You can pass a percentage value as string (eg. 20%) to nudge by the given percentage (relative to reference element size) Other supported units are vh and vw (relative to viewport) Additionally, you can pass a pair of values (eg. 10 20 or 2vh 20%) to nudge the popper on both axis. A note about percentage values, if you want to refer a percentage to the popper size instead of the reference element size, use %p instead of % (eg: 20%p). To make it clearer, you can replace % with %r and use eg.10%p 25%r. > Heads up! The order of the axis is relative to the popper placement: bottom or top are X,Y, the other are Y,X

Modifiers.preventOverflow(data, options) ⇒ Object

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 be ignore the boundary and "escape with the reference"

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

Kind: static method of Modifiers
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

Modifiers.shift(data, options) ⇒ Object

Modifier used to shift the popper on the start or end of its reference element side

Kind: static method of Modifiers
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

Modifiers.hide(data, options) ⇒ Object

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

Kind: static method of Modifiers
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

Modifiers.inner(data, options) ⇒ Object

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: static method of Modifiers
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

Modifiers~modifier ⇒ dataObject

Modifiers can edit the data object to change the beheavior of the popper. This object contains all the informations used by Popper.js to compute the popper position. The modifier can edit the data as needed, and then return it as result.

Kind: inner typedef of Modifiers
Returns: dataObject - modified data

Param Type
data dataObject

.createCallback : function

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

Kind: static typedef

Param Type
data dataObject

.updateCallback : function

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 typedef

Param Type
data dataObject