Constructors
Popper comes with two constructor functions to use.
They are small and unobtrusive.
Alternatively, support us onOpen Collective!
createPopper
ThecreatePopper constructor is at the heart of Popper. It allows you tocreate individual popper instances (objects) with state and methods.
Imports
// esmimport{ createPopper}from'@popperjs/core';// cjsconst{ createPopper}=require('@popperjs/core');// umdconst{ 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 likeflip maychange 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) versionof Popper includes all modifiers listed in the menu.
createPopper(reference, popper,{ modifiers:[{ name:'flip', enabled:false,},],});SeeModifiers for more information.
strategy
Describes the positioning strategy to use. By default, it isabsolute, whichin the simplest cases does not require repositioning of the popper.
If your reference element is in a fixed container, use thefixed 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 astateproperty 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
typeCreatePopper=( 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>|(($Shape<Options>)=>$Shape<Options>))=> Promise<$Shape<State>>,|};setOptions
You can update the options of a popper instance with thesetOptions method.
The method accepts either an options object or a function that takes the currentoptions object as argument and returns the new one.
Below we set a new configuration object that replaces the current one. Note thatthe below example will unset all the modifiers configuration and any othercustom options:
instance.setOptions({ placement:'bottom',});If, instead, we want to update the existing configuration, we can use a functionto read the current options and return updated ones (available since version2.10.0):
// Disable event listeners options without losing the rest of the set optionsinstance.setOptions(options=>({...options, modifiers:[...options.modifiers,{ name:'eventListeners', enabled:false}]}));// Enable it back, you can also use something like Ramda#assocPath to make this terserinstance.setOptions((options)=>R.assocPath(['modifiers'],{ name:'eventListeners', enabled:true}, options));popperGenerator
ThepopperGenerator constructor generates acreatePopper function. Thisallows you to configurecreatePopper with the functionality you need insteadof needing to pass the same defaults each time.
Imports
// esmimport{ popperGenerator}from'@popperjs/core';// cjsconst{ popperGenerator}=require('@popperjs/core');// umdconst{ popperGenerator}= Popper;Usage
const createPopper=popperGenerator({ defaultOptions:{ placement:'top'}, defaultModifiers:[popperOffsets, computeStyles, applyStyles, eventListeners],});// Now your custom `createPopper` is ready to use.Types
typePopperGenerator=(options?: PopperGeneratorOptions)=> CreatePopper;type PopperGeneratorOptions={ defaultModifiers?: Array<Modifier<any>>, defaultOptions?:$Shape<Options>,};