popper.js
Advanced tools
Package description
The popper.js npm package is a library used for managing poppers in web applications. Poppers are elements on the screen that 'pop out' from the flow of the document and float near a target element. The library is commonly used for tooltips, popovers, dropdowns, and similar components that require positioning near a reference element.
Positioning tooltips
This code sample demonstrates how to create a popper instance to position a tooltip above a button. The 'createPopper' function from popper.js is used to bind the tooltip to the button with a placement option set to 'top'.
import { createPopper } from '@popperjs/core';
const tooltip = document.querySelector('#tooltip');
const button = document.querySelector('#button');
const popperInstance = createPopper(button, tooltip, {
placement: 'top',
});Creating dropdowns
This code sample shows how to use popper.js to create a dropdown menu that appears below the start of a reference element. The 'createPopper' function is used to attach the dropdown to the reference element.
import { createPopper } from '@popperjs/core';
const dropdown = document.querySelector('#dropdown');
const referenceElement = document.querySelector('#referenceElement');
const popperInstance = createPopper(referenceElement, dropdown, {
placement: 'bottom-start',
});Modifying popper behavior with modifiers
This example illustrates how to use modifiers to alter the behavior of a popper. Here, an 'offset' modifier is added to provide a gap between the popper and the reference element.
import { createPopper } from '@popperjs/core';
const popper = document.querySelector('#popper');
const referenceElement = document.querySelector('#referenceElement');
const popperInstance = createPopper(referenceElement, popper, {
modifiers: [
{
name: 'offset',
options: {
offset: [0, 8],
},
},
],
});Tippy.js is a highly customizable tooltip and popover library powered by popper.js. It provides a simpler API for creating tooltips and popovers and includes additional features like animations and themes. It is built on top of popper.js and abstracts some of the complexity involved in creating poppers.
Tooltip.js is another library for creating and managing tooltips in web applications. It is also built on top of popper.js and provides a simpler interface for creating tooltips. However, it is less feature-rich compared to tippy.js and focuses mainly on tooltip functionality.
Floating UI is a low-level library for positioning floating elements. It is the successor to popper.js and provides more advanced features and better performance. It offers a more modular approach, allowing developers to import only the parts they need.
Readme
A library used to position poppers in web applications.
A popper is an element on the screen which "pops out" from the natural flow of your application.
Common examples of poppers are tooltips, popovers and drop-downs.
Well, basically, no.
Popper.js is a positioning engine, its purpose is to calculate the position of an element
to make it possible to position it near a given reference element.
The engine is completely modular and most of its features are implemented as modifiers
(similar to middlewares or plugins).
The whole code base is written in ES2015 and its features are automatically tested on real browsers thanks to SauceLabs and TravisCI.
Popper.js has zero dependencies. No jQuery, no LoDash, nothing.
It's used by big companies like Twitter in Bootstrap v4, Microsoft in WebClipper and Atlassian in AtlasKit.
This is the engine, the library that computes and, optionally, applies the styles to the poppers.
Some of the key points are:
Visit our project page to see a lot of examples of what you can do with Popper.js!
Find the documentation here.
Since lots of users just need a simple way to integrate powerful tooltips in their projects,
we created Tooltip.js.
It's a small library that makes it easy to automatically create tooltips using as engine Popper.js.
Its API is almost identical to the famous tooltip system of Bootstrap, in this way it will be
easy to integrate it in your projects.
The tooltips generated by Tooltip.js are accessible thanks to the aria tags.
Find the documentation here.
Popper.js is available on the following package managers and CDNs:
| Source | |
|---|---|
| npm | npm install popper.js --save |
| yarn | yarn add popper.js |
| NuGet | PM> Install-Package popper.js |
| Bower | bower install popper.js --save |
| unpkg | https://unpkg.com/popper.js |
| cdnjs | https://cdnjs.com/libraries/popper.js |
Tooltip.js as well:
| Source | |
|---|---|
| npm | npm install tooltip.js --save |
| yarn | yarn add tooltip.js |
| Bower* | bower install tooltip.js=https://unpkg.com/tooltip.js --save |
| unpkg | https://unpkg.com/tooltip.js |
| cdnjs | https://cdnjs.com/libraries/popper.js |
*: Bower isn't officially supported, it can be used to install Tooltip.js only trough the unpkg.com CDN. This method has the limitation of not being able to define a specific version of the library. Bower and Popper.js suggests to use npm or Yarn for your projects.
For more info, read the related issue.
Popper.js is currently shipped with 3 targets in mind: UMD, ESM and ESNext.
dist/, can be used with webpack and babel-preset-env;Make sure to use the right one for your needs. If you want to import it with a <script> tag, use UMD.
Given an existing popper DOM node, ask Popper.js to position it near its button
var reference = document.querySelector('.my-button');
var popper = document.querySelector('.my-popper');
var anotherPopper = new Popper(
reference,
popper,
{
// popper options here
}
);
Popper.js supports two kinds of callbacks, the onCreate callback is called after
the popper has been initialized. The onUpdate one is called on any subsequent update.
const reference = document.querySelector('.my-button');
const popper = document.querySelector('.my-popper');
new Popper(reference, popper, {
onCreate: (data) => {
// data is an object containing all the informations computed
// by Popper.js and used to style the popper and its arrow
// The complete description is available in Popper.js documentation
},
onUpdate: (data) => {
// same as `onCreate` but called on subsequent updates
}
});
Popper.js is based on a "plugin-like" architecture, most of its features are fully encapsulated "modifiers".
A modifier is a function that is called each time Popper.js needs to compute the position of the popper. For this reason, modifiers should be very performant to avoid bottlenecks.
To learn how to create a modifier, read the modifiers documentation
Integrating 3rd party libraries in React or other libraries can be a pain because
they usually alter the DOM and drive the libraries crazy.
Popper.js limits all its DOM modifications inside the applyStyle modifier,
you can simply disable it and manually apply the popper coordinates using
your library of choice.
For a comprehensive list of libraries that let you use Popper.js into existing frameworks, visit the MENTIONS page.
Alternatively, you may even override your own applyStyles with your custom one and
integrate Popper.js by yourself!
function applyReactStyle(data) {
// export data in your framework and use its content to apply the style to your popper
};
const reference = document.querySelector('.my-button');
const popper = document.querySelector('.my-popper');
new Popper(reference, popper, {
modifiers: {
applyStyle: { enabled: false },
applyReactStyle: {
enabled: true,
fn: applyReactStyle,
order: 800,
},
},
});
Since the API changed, we prepared some migration instructions to make it easy to upgrade to Popper.js v1.
https://github.com/FezVrasta/popper.js/issues/62
Feel free to comment inside the issue if you have any questions.
Popper.js is very performant. It usually takes 0.5ms to compute a popper's position (on an iMac with 3.5G GHz Intel Core i5).
This means that it will not cause any jank, leading to a smooth user experience.
The aim of Popper.js is to provide a stable and powerful positioning engine ready to be used in 3rd party libraries.
Visit the MENTIONS page for an updated list of projects.
I want to thank some friends and projects for the work they did:
Code and documentation copyright 2016 Federico Zivolo. Code released under the MIT license. Docs released under Creative Commons.
FAQs
A kickass library to manage your poppers
The npm package popper.js receives a total of 3,717,271 weekly downloads. As such, popper.js popularity was classified as popular.
We found that popper.js demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.
Security News
GitHub is susceptible to a CDN flaw that allows attackers to host malware on any public repository.