### Basic Popper.js Example with HTML and Script
Source: https://popper.js.org/docs/v2
A complete HTML example demonstrating how to use Popper.js to position a tooltip relative to a button. Ensure the Popper.js script is included before your custom script.
```html
Popper example
I'm a tooltip
```
--------------------------------
### Create Popper Instance
Source: https://popper.js.org/docs/v2/tutorial
Basic setup for Popper.js v2. Pass the reference element and the tooltip element to Popper.createPopper.
```html
Popper Tutorial
My tooltip
```
--------------------------------
### Install Popper.js with npm
Source: https://popper.js.org/docs/v2
Use npm to add Popper.js to your project dependencies.
```bash
# With npm
npm i @popperjs/core
```
--------------------------------
### Install Popper.js with Yarn
Source: https://popper.js.org/docs/v2
Use Yarn to add Popper.js to your project dependencies.
```bash
# With Yarn
yarn add @popperjs/core
```
--------------------------------
### Import Popper.js v1 (Modules)
Source: https://popper.js.org/docs/v2/migration-guide
In Popper 1, 'popper.js' was imported as a class. This example shows the v1 module import syntax.
```javascript
import Popper from 'popper.js';
new Popper(reference, popper, options);
```
--------------------------------
### Full Popper.js Tooltip Example
Source: https://popper.js.org/docs/v2/tutorial
A complete HTML file demonstrating a functional tooltip with Popper.js v2, including CSS styling, HTML structure, and JavaScript event handling for showing and hiding.
```html
Popper Tutorial
My tooltip
```
--------------------------------
### Import and Use detectOverflow
Source: https://popper.js.org/docs/v2/utils/detect-overflow
Import the `detectOverflow` utility from `@popperjs/core` and call it with the state and options. This is the basic setup for using the utility.
```javascript
import { detectOverflow } from '@popperjs/core';
const overflow = detectOverflow(state, options);
```
--------------------------------
### Make Popper Follow Mouse Cursor
Source: https://popper.js.org/docs/v2/virtual-elements
This example demonstrates how to make a popper follow the mouse cursor using a virtual element. It updates the virtual element's position on mouse movement and triggers a popper update.
```javascript
function generateGetBoundingClientRect(x = 0, y = 0) {
return () => ({
width: 0,
height: 0,
top: y,
right: x,
bottom: y,
left: x,
});
}
const virtualElement = {
getBoundingClientRect: generateGetBoundingClientRect(),
};
const instance = createPopper(virtualElement, popper);
document.addEventListener('mousemove', ({ clientX: x, clientY: y }) => {
virtualElement.getBoundingClientRect = generateGetBoundingClientRect(x, y);
instance.update();
});
```
--------------------------------
### Dynamic Offset Function
Source: https://popper.js.org/docs/v2/modifiers/offset
Use a function to dynamically calculate the offset based on placement and element dimensions. This example applies half the popper's height as margin when positioned below the reference.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'offset',
options: {
offset: ({ placement, reference, popper }) => {
if (placement === 'bottom') {
return [0, popper.height / 2];
} else {
return [];
}
},
},
},
],
});
```
--------------------------------
### Create and Use a Custom Modifier
Source: https://popper.js.org/docs/v2/modifiers
Define a custom modifier with a name, enabled state, phase, and a function to execute logic. This example logs to the console when the Popper is positioned at the 'top'.
```javascript
const topLogger = {
name: 'topLogger',
enabled: true,
phase: 'main',
fn({ state }) {
if (state.placement === 'top') {
console.log('Popper is on the top');
}
},
};
createPopper(reference, popper, {
modifiers: [topLogger],
});
```
--------------------------------
### createPopper with Disabled Modifier
Source: https://popper.js.org/docs/v2/constructors
Customize popper behavior by configuring modifiers. This example disables the `flip` modifier.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'flip',
enabled: false,
},
],
});
```
--------------------------------
### Configure Built-in Modifier Options
Source: https://popper.js.org/docs/v2/modifiers
Override options for a built-in modifier by providing an object with the modifier's name and a new options property. This example configures the 'flip' modifier to use specific fallback placements.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'flip',
options: {
fallbackPlacements: ['top', 'bottom'],
},
},
],
});
```
--------------------------------
### Basic createPopper Usage
Source: https://popper.js.org/docs/v2/constructors
Initialize a popper instance by providing the reference and popper elements, along with an optional options object.
```javascript
const reference = document.querySelector('#reference');
const popper = document.querySelector('#popper');
createPopper(reference, popper, {
// options
});
```
--------------------------------
### Importing Popper Lite for Tree-shaking
Source: https://popper.js.org/docs/v2/performance
Use this import path to enable tree-shaking with Popper Lite. This excludes unused features and significantly reduces bundle size.
```javascript
import { createPopper } from '@popperjs/core/lib/popper-lite';
```
--------------------------------
### Custom Modifier to Hide Arrow
Source: https://popper.js.org/docs/v2/modifiers/arrow
An example of a custom modifier that hides the arrow when it reaches the edge of the popper and can no longer point to the center of the reference element.
```APIDOC
## Custom Modifier Example
If you would like to hide the arrow once it reaches the edge of its popper (i.e. once it can no longer point to the center of the reference element), you can create a custom modifier:
```javascript
const applyArrowHide = {
name: 'applyArrowHide',
enabled: true,
phase: 'write',
fn({ state }) {
const { arrow } = state.elements;
if (arrow) {
if (state.modifiersData.arrow.centerOffset !== 0) {
arrow.setAttribute('data-hide', '');
} else {
arrow.removeAttribute('data-hide');
}
}
},
};
```
And the corresponding CSS:
```css
.arrow[data-hide] {
visibility: hidden;
}
```
```
--------------------------------
### Include Popper.js via CDN (Production)
Source: https://popper.js.org/docs/v2
Include the production version of Popper.js from a CDN for use in your live application.
```html
```
--------------------------------
### Include Popper.js via CDN (Development)
Source: https://popper.js.org/docs/v2
Include the development version of Popper.js from a CDN for testing or development purposes.
```html
```
--------------------------------
### createPopper
Source: https://popper.js.org/docs/v2/constructors
The `createPopper` constructor is the primary way to create individual popper instances. It allows for extensive customization through options and modifiers.
```APIDOC
## createPopper
### Description
The `createPopper` constructor is at the heart of Popper. It allows you to create individual popper instances (objects) with state and methods.
### Imports
```javascript
// esm
import { createPopper } from '@popperjs/core';
// cjs
const { createPopper } = require('@popperjs/core');
// umd
const { createPopper } = Popper;
```
### Usage
```javascript
const reference = document.querySelector('#reference');
const popper = document.querySelector('#popper');
createPopper(reference, popper, {
// options
});
```
### Options
```typescript
type Options = {|
placement?: Placement, // "bottom"
modifiers?: Array<$Shape>>, // []
strategy?: PositioningStrategy, // "absolute",
onFirstUpdate?: ($Shape) => 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 like `flip` may change the placement of the popper to make it fit better.
```javascript
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) version of Popper includes all modifiers listed in the menu.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'flip',
enabled: false,
},
],
});
```
See Modifiers for more information.
#### `strategy`
Describes the positioning strategy to use. By default, it is `absolute`, which in the simplest cases does not require repositioning of the popper.
If your reference element is in a fixed container, use the `fixed` strategy:
```javascript
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 a `state` property and some methods.
Log it out in DevTools:
```javascript
const instance = createPopper(reference, popper);
console.log(instance);
```
```json
{
// 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
```typescript
type CreatePopper = (
reference: Element | VirtualElement,
popper: HTMLElement,
options?: Options
) => Instance;
type Options = {|
placement: Placement,
modifiers: Array<$Shape>>,
strategy: PositioningStrategy,
onFirstUpdate?: ($Shape) => void,
|};
type Instance = {|
state: State,
destroy: () => void,
forceUpdate: () => void,
update: () => Promise<$Shape>,
setOptions: (
options: $Shape | (($Shape) => $Shape)
) => Promise<$Shape>,
|};
```
```
--------------------------------
### Manually Update Popper Instance
Source: https://popper.js.org/docs/v2/lifecycle
Call `instance.update()` to recompute the tooltip's position. This method returns a promise that resolves with the updated state.
```javascript
const state = await popperInstance.update();
```
--------------------------------
### createPopper with Specific Placement
Source: https://popper.js.org/docs/v2/constructors
Configure the preferred placement of the popper using the `placement` option. Modifiers like `flip` can adjust this dynamically.
```javascript
createPopper(reference, popper, {
placement: 'right-start',
});
```
--------------------------------
### Using Popper Lite with Specific Modifiers
Source: https://popper.js.org/docs/v2/performance
Import Popper Lite and explicitly include desired modifiers like `flip` and `preventOverflow` to minimize bundle size. This approach is recommended for performance-critical applications.
```javascript
import { createPopper } from '@popperjs/core/lib/popper-lite';
import flip from '@popperjs/core/lib/modifiers/flip';
import preventOverflow from '@popperjs/core/lib/modifiers/preventOverflow';
createPopper(reference, popper, {
modifiers: [flip, preventOverflow],
});
```
--------------------------------
### Hook into First Update with onFirstUpdate
Source: https://popper.js.org/docs/v2/lifecycle
Use the `onFirstUpdate` option during Popper initialization to execute a callback function once the element has been positioned for the first time. The callback receives the state object.
```javascript
createPopper(referenceElement, popperElement, {
onFirstUpdate: state => console.log('Popper positioned on', state.placement),
});
```
--------------------------------
### Customize Tethering with an Offset
Source: https://popper.js.org/docs/v2/modifiers/prevent-overflow
Use `tetherOffset` to customize the tethering behavior. A positive offset activates tethering earlier, while a negative offset delays it. It can also accept a function to dynamically calculate the offset based on popper and reference dimensions or placement.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'preventOverflow',
options: {
tetherOffset: ({ popper, reference, placement }) => popper.width / 2,
},
},
],
});
```
--------------------------------
### Import createPopper Constructor
Source: https://popper.js.org/docs/v2/constructors
Import the `createPopper` constructor from the `@popperjs/core` package for use in your project. Supports ES Modules, CommonJS, and UMD formats.
```javascript
// esm
import { createPopper } from '@popperjs/core';
```
```javascript
// cjs
const { createPopper } = require('@popperjs/core');
```
```javascript
// umd
const { createPopper } = Popper;
```
--------------------------------
### Update Popper Instance Options Functionally
Source: https://popper.js.org/docs/v2/constructors
Use a function with `setOptions` to update existing configurations without losing other settings. This is available from version 2.10.0.
```javascript
// Disable event listeners options without losing the rest of the set options
instance.setOptions(options => ({
...options,
modifiers: [
...options.modifiers,
{ name: 'eventListeners', enabled: false }
]
}));
```
```javascript
// Enable it back, you can also use something like Ramda#assocPath to make this terser
instance.setOptions((options) =>
R.assocPath(['modifiers'], { name: 'eventListeners', enabled: true }, options)
);
```
--------------------------------
### Dynamic Offset with Media Queries
Source: https://popper.js.org/docs/v2/faq
Use `window.matchMedia()` with a function for the `offset` modifier to dynamically adjust the popper's offset based on browser width.
```javascript
const mediaQuery = window.matchMedia('(max-width: 500px)');
createPopper(reference, popper, {
modifiers: [
{
name: 'offset',
options: {
// 0px distance at <= 500px width, otherwise 10px distance
offset: () => [0, mediaQuery.matches ? 0 : 10],
},
},
],
});
```
--------------------------------
### Import Popper.js v2 (CDN / UMD)
Source: https://popper.js.org/docs/v2/migration-guide
For CDN or UMD builds, Popper 2's createPopper function is available under the global 'Popper' namespace.
```javascript
Popper.createPopper;
```
--------------------------------
### Configure Modifier Defaults and Overrides
Source: https://popper.js.org/docs/v2/faq
Demonstrates how to set default modifier options and allow them to be overridden by user-provided configurations. Modifiers are merged by name, with later entries taking precedence.
```javascript
// A user passes this object in:
const popperOptions = {
strategy: 'fixed',
modifiers: [
{
name: 'preventOverflow',
options: {
padding: 0,
},
},
],
};
// Your library sets its own defaults:
createPopper(reference, popper, {
...popperOptions,
modifiers: [
{
name: 'preventOverflow',
options: {
rootBoundary: 'document',
padding: 10,
},
},
...(popperOptions.modifiers || []),
],
});
```
--------------------------------
### Import Popper Lite
Source: https://popper.js.org/docs/v2
Import the 'popper-lite' version for a smaller bundle size. This version includes essential modifiers for basic functionality.
```javascript
import { createPopper } from '@popperjs/core/lib/popper-lite.js';
```
--------------------------------
### setOptions Method
Source: https://popper.js.org/docs/v2/constructors
The `setOptions` method allows you to update the configuration of a Popper instance. You can pass either a new options object to replace the current configuration or a function that takes the current options and returns the updated ones.
```APIDOC
## `setOptions` Method
### Description
Updates the options of a popper instance. Accepts an options object or a function that returns new options.
### Usage
// Replace all options with a new configuration
`instance.setOptions({ placement: 'bottom' });`
// Update existing configuration using a function (available since v2.10.0)
`instance.setOptions(options => ({
...options,
modifiers: [
...options.modifiers,
{ name: 'eventListeners', enabled: false }
]
}));`
// Example using Ramda for terser updates
`instance.setOptions((options) => R.assocPath(['modifiers'], { name: 'eventListeners', enabled: true }, options));`
```
--------------------------------
### Import popperGenerator
Source: https://popper.js.org/docs/v2/constructors
Import the `popperGenerator` function from the `@popperjs/core` package for different module systems.
```javascript
// esm
import { popperGenerator } from '@popperjs/core';
```
```javascript
// cjs
const { popperGenerator } = require('@popperjs/core');
```
```javascript
// umd
const { popperGenerator } = Popper;
```
--------------------------------
### Update Popper Instance Options
Source: https://popper.js.org/docs/v2/constructors
Use `setOptions` to replace the entire configuration object. This will unset all previous modifiers and custom options.
```javascript
instance.setOptions({
placement: 'bottom',
});
```
--------------------------------
### Update Popper Instance with New Options
Source: https://popper.js.org/docs/v2/lifecycle
Setting new options on the Popper instance, such as `placement`, will internally trigger an `update()` call. The method returns a promise resolving with the updated state.
```javascript
const state = await popperInstance.setOptions({ placement: 'bottom' });
```
--------------------------------
### Logging Popper Instance
Source: https://popper.js.org/docs/v2/constructors
Access the popper instance returned by `createPopper` to interact with its state and methods.
```javascript
const instance = createPopper(reference, popper);
console.log(instance);
```
--------------------------------
### Basic Tooltip Styling
Source: https://popper.js.org/docs/v2/tutorial
Applies basic styling to the tooltip element, including background, color, padding, and border-radius.
```html
Popper Tutorial
```
--------------------------------
### Import Popper.js v2 (Modules)
Source: https://popper.js.org/docs/v2/migration-guide
Popper 2 uses a function-based import from '@popperjs/core'. This is the standard way to import the core functionality in v2.
```javascript
import { createPopper } from '@popperjs/core';
createPopper(reference, popper, options);
```
--------------------------------
### Configure altBoundary for detectOverflow
Source: https://popper.js.org/docs/v2/utils/detect-overflow
Enable checking the alternative element's boundary. If checking the popper, it checks the reference's boundary, and vice-versa.
```javascript
detectOverflow(state, {
altBoundary: true, // false by default
});
```
--------------------------------
### Popper Instance Structure
Source: https://popper.js.org/docs/v2/constructors
A Popper instance is a plain object containing the popper's state and methods for updating and cleanup.
```javascript
{
// 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() {},
}
```
--------------------------------
### Import createPopper from Popper.js for Module Bundlers
Source: https://popper.js.org/docs/v2
Import the `createPopper` function from the Popper.js core library when using module bundlers like Webpack or Rollup. This approach allows for tree-shaking and efficient bundling.
```javascript
import { createPopper } from '@popperjs/core';
const button = document.querySelector('#button');
const tooltip = document.querySelector('#tooltip');
// Pass the button, the tooltip, and some options, and Popper will do the
// magic positioning for you:
createPopper(button, tooltip, {
placement: 'right',
});
```
--------------------------------
### Create a Custom createPopper Function
Source: https://popper.js.org/docs/v2/constructors
Use `popperGenerator` to create a `createPopper` function with predefined default options and modifiers.
```javascript
const createPopper = popperGenerator({
defaultOptions: { placement: 'top' },
defaultModifiers: [popperOffsets, computeStyles, applyStyles, eventListeners],
});
// Now your custom `createPopper` is ready to use.
```
--------------------------------
### Configure padding for detectOverflow
Source: https://popper.js.org/docs/v2/utils/detect-overflow
Apply virtual padding to the boundary. This can be a single number for uniform padding or an object for specific side padding.
```javascript
detectOverflow(state, {
// Same padding on all four sides
padding: 8,
// Different padding on certain sides – unspecified sides are 0
padding: { top: 8, right: 16 },
});
```
--------------------------------
### Tooltip Event Handling Logic
Source: https://popper.js.org/docs/v2/tutorial
Manages showing and hiding the tooltip based on `mouseenter`, `focus`, `mouseleave`, and `blur` events. It also updates the Popper instance when the tooltip is shown.
```javascript
function show() {
tooltip.setAttribute('data-show', '');
// We need to tell Popper to update the tooltip position
// after we show the tooltip, otherwise it will be incorrect
popperInstance.update();
}
function hide() {
tooltip.removeAttribute('data-show');
}
const showEvents = ['mouseenter', 'focus'];
const hideEvents = ['mouseleave', 'blur'];
showEvents.forEach((event) => {
button.addEventListener(event, show);
});
hideEvents.forEach((event) => {
button.addEventListener(event, hide);
});
```
--------------------------------
### Configure rootBoundary for detectOverflow
Source: https://popper.js.org/docs/v2/utils/detect-overflow
Set the root boundary for overflow detection. Options are 'viewport' (default) for the visible area or 'document' for the entire scrollable page.
```javascript
detectOverflow(state, {
rootBoundary: 'document', // 'viewport' by default
});
```
--------------------------------
### Set Root Boundary
Source: https://popper.js.org/docs/v2/modifiers/prevent-overflow
Configure the `rootBoundary` option for `preventOverflow` to define the boundary context. Common values include 'viewport' or 'document'.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'preventOverflow',
options: {
rootBoundary: 'document',
},
},
],
});
```
--------------------------------
### Offset Modifier Configuration
Source: https://popper.js.org/docs/v2/modifiers/offset
This snippet demonstrates how to configure the 'offset' modifier with an array of [skidding, distance] values.
```APIDOC
## Offset Modifier
### Description
The `offset` modifier lets you displace a popper element from its reference element.
### Method
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'offset',
options: {
offset: [10, 20],
},
},
],
});
```
### Options
#### `offset`
Accepts an array with two numbers in the form `[skidding, distance]`.
- **skidding** (number) - Displaces the popper along the reference element.
- **distance** (number) - Displaces the popper away from, or toward, the reference element in the direction of its placement. A positive number displaces it further away, while a negative number lets it overlap the reference.
```
--------------------------------
### popperGenerator Constructor
Source: https://popper.js.org/docs/v2/constructors
The `popperGenerator` constructor creates a `createPopper` function with pre-configured default options and modifiers, simplifying the creation of Popper instances with consistent settings.
```APIDOC
## `popperGenerator` Constructor
### Description
Generates a `createPopper` function with custom default configurations.
### Imports
```javascript
// esm
import { popperGenerator } from '@popperjs/core';
// cjs
const { popperGenerator } = require('@popperjs/core');
// umd
const { popperGenerator } = Popper;
```
### Usage
```javascript
const createPopper = popperGenerator({
defaultOptions: { placement: 'top' },
defaultModifiers: [popperOffsets, computeStyles, applyStyles, eventListeners],
});
// Now use the custom `createPopper` function
```
### Types
```typescript
type PopperGenerator = (options?: PopperGeneratorOptions) => CreatePopper;
type PopperGeneratorOptions = {
defaultModifiers?: Array>,
defaultOptions?: $Shape,
};
```
```
--------------------------------
### Tooltip CSS for Visibility
Source: https://popper.js.org/docs/v2/tutorial
Defines the default hidden state and the visible state of the tooltip using the `data-show` attribute.
```css
#tooltip {
/* ... */
display: none;
}
#tooltip[data-show] {
display: block;
}
```
--------------------------------
### Offset Modifier with Function
Source: https://popper.js.org/docs/v2/modifiers/offset
This snippet shows how to use a function for the offset option, providing dynamic control based on placement and element dimensions.
```APIDOC
## Offset Modifier with Function
### Description
The `offset` modifier can also accept a function for dynamic positioning.
### Method
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'offset',
options: {
offset: ({ placement, reference, popper }) => {
if (placement === 'bottom') {
return [0, popper.height / 2];
} else {
return [];
}
},
},
},
],
});
```
### Options
#### `offset` Function
Provides access to `placement`, `reference` rect, and `popper` rect for custom offset calculations.
- **placement** (Placement) - The current placement of the popper.
- **reference** (Rect) - The bounding rectangle of the reference element.
- **popper** (Rect) - The bounding rectangle of the popper element.
Returns an array `[skidding, distance]` or an empty array.
```
--------------------------------
### Use Standards Mode Doctype
Source: https://popper.js.org/docs/v2/faq
Ensure your HTML document uses the Standards Mode doctype to avoid positioning issues with the `computeStyles` modifier.
```html
```
--------------------------------
### Basic Offset Configuration
Source: https://popper.js.org/docs/v2/modifiers/offset
Configure the offset modifier with fixed skidding and distance values. The first number is skidding (horizontal offset), and the second is distance (vertical offset).
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'offset',
options: {
offset: [10, 20],
},
},
],
});
```
--------------------------------
### Structure for CSS Transitions
Source: https://popper.js.org/docs/v2/faq
To apply CSS transitions without disabling the `adaptive` option, wrap the popper's content in an inner element that handles the transitions.
```html
Content
```
--------------------------------
### Enable Strict Modifier Type Checking with Flow
Source: https://popper.js.org/docs/v2/typings
Opt-in to strict type checking for modifiers in `createPopper` by importing `StrictModifiers`. This ensures that all provided modifiers adhere to the expected types.
```flow
// @flow
import { createPopper } from '@popperjs/core';
import type { StrictModifiers } from '@popperjs/core';
```
--------------------------------
### Use Alternative Boundary Context
Source: https://popper.js.org/docs/v2/modifiers/prevent-overflow
Enable `altBoundary` to use the reference's boundary context, similar to `scrollParent` in Popper v1. This checks the clipping parents of the reference element.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'preventOverflow',
options: {
altBoundary: true, // false by default
},
},
],
});
```
--------------------------------
### Configure allowedAutoPlacements for Flip Modifier
Source: https://popper.js.org/docs/v2/modifiers/flip
Restrict the 'auto' placement to only 'top' or 'bottom' by setting `allowedAutoPlacements` within the flip modifier's options. This ensures that the Popper will only attempt to resolve to these specified placements.
```javascript
createPopper(reference, popper, {
placement: 'auto',
modifiers: [
{
name: 'flip',
options: {
allowedAutoPlacements: ['top', 'bottom'], // by default, all the placements are allowed
},
},
],
});
```
--------------------------------
### Custom Offset Rounding in computeStyles
Source: https://popper.js.org/docs/v2/modifiers/compute-styles
Provide a custom function to the `roundOffsets` option to control how popper offsets are rounded. This allows for fine-grained control over positioning to prevent blurriness or adjust for specific subpixel rendering behaviors.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'computeStyles',
options: {
roundOffsets: ({ x, y }) => ({
x: Math.round(x + 2),
y: Math.round(y + 2),
}),
},
},
],
});
```
--------------------------------
### Configuring Popper Generator with Default Modifiers
Source: https://popper.js.org/docs/v2/performance
Utilize `popperGenerator` to create a custom `createPopper` function with a predefined set of default modifiers, including additional ones like `flip` and `preventOverflow`.
```javascript
import {
popperGenerator,
defaultModifiers,
} from '@popperjs/core/lib/popper-lite';
import flip from '@popperjs/core/lib/modifiers/flip';
import preventOverflow from '@popperjs/core/lib/modifiers/preventOverflow';
const createPopper = popperGenerator({
defaultModifiers: [...defaultModifiers, flip, preventOverflow],
});
// Now you can use `createPopper`
```
--------------------------------
### Compute Styles Modifier Configuration
Source: https://popper.js.org/docs/v2/modifiers/compute-styles
This modifier prepares the styles that will be written to the DOM in the next phase. It includes options for GPU acceleration, adaptive positioning, and rounding offsets.
```APIDOC
## Compute Styles Modifier
The `computeStyles` modifier prepares the styles that will get written to the DOM in the next phase, `write`. This includes rounding the offsets and deciding what properties to use (e.g. `gpuAcceleration`).
### Phase
`beforeWrite`
### Options
```typescript
type Options = {
gpuAcceleration: boolean,
adaptive: boolean,
roundOffsets: boolean | RoundOffsets, // true by default
};
type RoundOffsets = (
offsets: $Shape<{ x: number, y: number, centerOffset: numberТеги}>
) => {|
y: number,
x: number,
|};
```
#### `gpuAcceleration`
This determines whether GPU-accelerated styles are used to position the popper.
* `true`: Popper will use the 3D transforms on high PPI displays and 2D transforms on low PPI displays.
* `false`: Popper will use `top/left` properties.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'computeStyles',
options: {
gpuAcceleration: false, // true by default
},
},
],
});
```
#### `adaptive`
This option, enabled by default, tells Popper to use the most suitable CSS properties to position the popper (either `top` and `left`, or `bottom` and `right`).
This allows the popper content to change, and reduce the likelihood of needing to recompute the popper position.
For example, if our popper is positioned on the left of its reference element, Popper will apply `right: 0px` and `translate3d(-200px, 0px, 0px)`. Doing so, if the content of the popper changes, making it wider or narrower, the popper will stay anchored to its reference element.
This behavior can be disabled by setting the option to `false`:
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'computeStyles',
options: {
adaptive: false, // true by default
},
},
],
});
```
#### `roundOffsets`
This determines whether try to round offsets to the nearest suitable subpixel based on the device pixel ratio.
Rounded offsets are useful to prevent blurriness on some browsers, but may lead to slight positioning issues (1px off).
When the option is set to `false`, the offsets will not be rounded, so you may receive decimal values that don't fit in the device subpixel grid.
You can optionally set this to a function to provide your own offset logic, example:
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'computeStyles',
options: {
roundOffsets: ({ x, y }) => ({
x: Math.round(x + 2),
y: Math.round(y + 2),
}),
},
},
],
});
```
## Data
This modifier currently has no data.
```
--------------------------------
### Flip Modifier with Fallback Placements
Source: https://popper.js.org/docs/v2/modifiers/flip
Configures the flip modifier to try 'top' and 'right' placements if the initial 'left' placement overflows. If none of the fallbacks fit, it reverts to the original placement.
```javascript
createPopper(reference, popper, {
placement: 'left',
modifiers: [
{
name: 'flip',
options: {
fallbackPlacements: ['top', 'right'],
},
},
],
});
```
--------------------------------
### Disable Adaptive Positioning in computeStyles
Source: https://popper.js.org/docs/v2/modifiers/compute-styles
Set `adaptive` to `false` to disable Popper's automatic adjustment of positioning properties (e.g., using `bottom`/`right` instead of `top`/`left`). This ensures consistent use of `top`/`left` properties.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'computeStyles',
options: {
adaptive: false, // true by default
},
},
],
});
```
--------------------------------
### Arrow Styling
Source: https://popper.js.org/docs/v2/tutorial
Styles the arrow element and its pseudo-element for positioning. The `::before` pseudo-element is used for rotation.
```css
#arrow,
#arrow::before {
position: absolute;
width: 8px;
height: 8px;
background: inherit;
}
#arrow {
visibility: hidden;
}
#arrow::before {
visibility: visible;
content: '';
transform: rotate(45deg);
}
```
--------------------------------
### Apply 'fixed' Positioning Strategy
Source: https://popper.js.org/docs/v2/faq
When the reference element has `position: fixed`, use the `'fixed'` strategy to prevent popper jittering during scrolling.
```javascript
createPopper(reference, popper, {
strategy: 'fixed',
});
```
--------------------------------
### Enable Alternative Axis Check
Source: https://popper.js.org/docs/v2/modifiers/prevent-overflow
Enable the `altAxis` option to check the alternative axis. This may cause the popper to overlap its reference, and is often used with the `flip` modifier.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'preventOverflow',
options: {
altAxis: true, // false by default
},
},
],
});
```
--------------------------------
### IE11 Polyfill Script
Source: https://popper.js.org/docs/v2/browser-support
Include this script to enable Popper.js v2 functionality in Internet Explorer 11 and older browsers. Browsers that do not require these polyfills will not be affected by the additional JS bundle size.
```html
```
--------------------------------
### Configure boundary for detectOverflow
Source: https://popper.js.org/docs/v2/utils/detect-overflow
Define the area against which overflow is checked. By default, it uses 'clippingParents', which are scrolling containers that might hide the element.
```javascript
const customBoundary = document.querySelector('#boundary');
detectOverflow(state, {
boundary: customBoundary, // 'clippingParents' by default
});
```
--------------------------------
### Set Padding for Prevent Overflow
Source: https://popper.js.org/docs/v2/modifiers/prevent-overflow
Configure the `padding` option for the `preventOverflow` modifier to add space around the popper within its boundary. This value is in pixels.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'preventOverflow',
options: {
padding: 8,
},
},
],
});
```
--------------------------------
### Import Specific Modifier with Flow
Source: https://popper.js.org/docs/v2/typings
Import individual modifier modules directly from the library. Flow will automatically infer the types for the imported module.
```flow
import hideModifier from '@popperjs/core/lib/modifiers/hide';
```
--------------------------------
### Arrow Placement Styling
Source: https://popper.js.org/docs/v2/tutorial
Offsets the arrow based on the popper's placement using `data-popper-placement`. The `^=` selector handles variations like `top-start`.
```css
#tooltip[data-popper-placement^='top'] > #arrow {
bottom: -4px;
}
#tooltip[data-popper-placement^='bottom'] > #arrow {
top: -4px;
}
#tooltip[data-popper-placement^='left'] > #arrow {
right: -4px;
}
#tooltip[data-popper-placement^='right'] > #arrow {
left: -4px;
}
```
--------------------------------
### Hide Popper CSS
Source: https://popper.js.org/docs/v2/modifiers/hide
Apply this CSS to hide the popper when its reference element is clipped and hidden from view. Avoid using `display: none` as it can cause jitter issues.
```css
#popper[data-popper-reference-hidden] {
visibility: hidden;
pointer-events: none;
}
```
--------------------------------
### Configure elementContext for detectOverflow
Source: https://popper.js.org/docs/v2/utils/detect-overflow
Specify which element's overflow to check relative to the boundary. By default, it checks the popper element's overflow.
```javascript
detectOverflow(state, {
elementContext: 'reference', // 'popper' by default
});
```
--------------------------------
### Specify Boundary Element
Source: https://popper.js.org/docs/v2/modifiers/prevent-overflow
Set a specific HTML element as the boundary for the `preventOverflow` modifier. The popper will be constrained within this element.
```javascript
const element = document.querySelector('#parentElement');
createPopper(reference, popper, {
modifiers: [
{
name: 'preventOverflow',
options: {
boundary: element,
},
},
],
});
```
--------------------------------
### Flip Modifier with Alt Boundary
Source: https://popper.js.org/docs/v2/modifiers/flip
Enables the altBoundary option for the flip modifier. This makes the modifier check the reference element's boundary context instead of the popper's.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'flip',
options: {
altBoundary: true, // false by default
},
},
],
});
```
--------------------------------
### Disable GPU Acceleration in computeStyles
Source: https://popper.js.org/docs/v2/modifiers/compute-styles
Set `gpuAcceleration` to `false` to use `top/left` properties instead of transforms for positioning. This is useful for specific styling needs or compatibility.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'computeStyles',
options: {
gpuAcceleration: false, // true by default
},
},
],
});
```
--------------------------------
### Flip Modifier with Root Boundary
Source: https://popper.js.org/docs/v2/modifiers/flip
Configures the flip modifier to use the 'document' as its root boundary, allowing it to overflow the viewport if necessary.
```javascript
createPopper(reference, popper, {
modifiers: [
{
name: 'flip',
options: {
rootBoundary: 'document',
},
},
],
});
```