- dataObject
The
dataObject
is an object containing all the informations used by Popper.js this object get passed to modifiers and to theonCreate
andonUpdate
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
- 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
andonLoad
props. All the other properties are configurations that could be tweaked.
- 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 class
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 |
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
Popper's placement
Kind: static property of Defaults
Properties
Name | Type | Default |
---|---|---|
placement | placements |
'bottom' |
Whether events (resize, scroll) are initially enabled
Kind: static property of Defaults
Properties
Name | Type | Default |
---|---|---|
eventsEnabled | Boolean |
true |
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 |
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 |
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 |
---|
onCreate |
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 |
---|
onUpdate |
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
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
Destroy the popper
Kind: static method of Popper
It will add resize/scroll events and start recalculating position of the popper element when they are triggered.
Kind: static method of Popper
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
Schedule an update, it will run on the next UI update available
Kind: static method of Popper
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.arrow | Object |
top and left offsets, only one of them will be different from 0 |
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 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
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
Kind: static property of shift
Properties
Name | Type | Default | Description |
---|---|---|---|
order | number |
100 |
Index used to define the order of execution |
Kind: static property of shift
Properties
Name | Type | Default | Description |
---|---|---|---|
enabled | Boolean |
true |
Whether the modifier is enabled or not |
Kind: static property of shift
Properties
Type |
---|
ModifierFn |
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 elementvw
, CSS viewport width unitvh
, 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
Kind: static property of offset
Properties
Name | Type | Default | Description |
---|---|---|---|
order | number |
200 |
Index used to define the order of execution |
Kind: static property of offset
Properties
Name | Type | Default | Description |
---|---|---|---|
enabled | Boolean |
true |
Whether the modifier is enabled or not |
Kind: static property of offset
Properties
Type |
---|
ModifierFn |
Kind: static property of offset
Properties
Name | Type | Default | Description |
---|---|---|---|
offset | Number | String |
0 |
The offset value as described in the modifier description |
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
Kind: static property of preventOverflow
Properties
Name | Type | Default | Description |
---|---|---|---|
order | number |
300 |
Index used to define the order of execution |
Kind: static property of preventOverflow
Properties
Name | Type | Default | Description |
---|---|---|---|
enabled | Boolean |
true |
Whether the modifier is enabled or not |
Kind: static property of preventOverflow
Properties
Type |
---|
ModifierFn |
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 |
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 |
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. |
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
Kind: static property of keepTogether
Properties
Name | Type | Default | Description |
---|---|---|---|
order | number |
400 |
Index used to define the order of execution |
Kind: static property of keepTogether
Properties
Name | Type | Default | Description |
---|---|---|---|
enabled | Boolean |
true |
Whether the modifier is enabled or not |
Kind: static property of keepTogether
Properties
Type |
---|
ModifierFn |
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
Kind: static property of arrow
Properties
Name | Type | Default | Description |
---|---|---|---|
order | number |
500 |
Index used to define the order of execution |
Kind: static property of arrow
Properties
Name | Type | Default | Description |
---|---|---|---|
enabled | Boolean |
true |
Whether the modifier is enabled or not |
Kind: static property of arrow
Properties
Type |
---|
ModifierFn |
Kind: static property of arrow
Properties
Name | Type | Default | Description |
---|---|---|---|
element | String | HTMLElement |
'[x-arrow]' |
Selector or node used as arrow |
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
Kind: static property of flip
Properties
Name | Type | Default | Description |
---|---|---|---|
order | number |
600 |
Index used to define the order of execution |
Kind: static property of flip
Properties
Name | Type | Default | Description |
---|---|---|---|
enabled | Boolean |
true |
Whether the modifier is enabled or not |
Kind: static property of flip
Properties
Type |
---|
ModifierFn |
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). |
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 |
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) |
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
Kind: static property of inner
Properties
Name | Type | Default | Description |
---|---|---|---|
order | number |
700 |
Index used to define the order of execution |
Kind: static property of inner
Properties
Name | Type | Default | Description |
---|---|---|---|
enabled | Boolean |
false |
Whether the modifier is enabled or not |
Kind: static property of inner
Properties
Type |
---|
ModifierFn |
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
Kind: static property of hide
Properties
Name | Type | Default | Description |
---|---|---|---|
order | number |
800 |
Index used to define the order of execution |
Kind: static property of hide
Properties
Name | Type | Default | Description |
---|---|---|---|
enabled | Boolean |
true |
Whether the modifier is enabled or not |
Kind: static property of hide
Properties
Type |
---|
ModifierFn |
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
Kind: static property of applyStyle
Properties
Name | Type | Default | Description |
---|---|---|---|
order | number |
900 |
Index used to define the order of execution |
Kind: static property of applyStyle
Properties
Name | Type | Default | Description |
---|---|---|---|
enabled | Boolean |
true |
Whether the modifier is enabled or not |
Kind: static property of applyStyle
Properties
Type |
---|
ModifierFn |
Kind: static property of applyStyle
Properties
Type |
---|
function |
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 |
Kind: global typedef
Param | Type |
---|---|
data | dataObject |
Kind: global typedef
Param | Type |
---|---|
data | dataObject |