@popperjs/core

What is @popperjs/core?

The @popperjs/core package is a powerful positioning engine that allows developers to position elements on a webpage in relation to a reference element. This is particularly useful for creating tooltips, popovers, dropdowns, and more, ensuring they are positioned correctly regardless of viewport size or element positioning.

What are @popperjs/core's main functionalities?

Creating a Tooltip

This code sample demonstrates how to create a simple tooltip positioned to the right of a button. It uses the `createPopper` function from @popperjs/core to dynamically position the tooltip element in relation to the button element.

import { createPopper } from '@popperjs/core';

const tooltip = document.querySelector('#tooltip');
const button = document.querySelector('#button');

createPopper(button, tooltip, {
  placement: 'right',
});

Modifying Popper Behavior with Modifiers

This example shows how to use modifiers to adjust the behavior of a Popper instance. Here, the 'offset' modifier is used to add some space between the reference element and the popper element, specifically 8 pixels along the y-axis.

import { createPopper } from '@popperjs/core';

const popperInstance = createPopper(referenceElement, popperElement, {
  modifiers: [
    {
      name: 'offset',
      options: {
        offset: [0, 8],
      },
    },
  ],
});

Other packages similar to @popperjs/core

tippy.js

Tippy.js is a highly customizable tooltip and popover library that wraps around Popper.js. It offers a simpler API for common tooltip and popover scenarios, making it easier to use out of the box compared to @popperjs/core, which offers more low-level control.

floating-ui

Floating UI is a low-level library for creating floating elements, tooltips, dropdowns, and more, similar to @popperjs/core. It provides a core set of utilities for positioning and updating the UI elements, with a focus on extensibility and customization.

README

Positioning tooltips (but also dropdowns, popovers, and more) is difficult. Popper is here to help!

Given a reference element (such as a button) and a tooltip element, Popper will automatically put your tooltip in the right place next to the button.

Why Popper?

Naive tooltip implementations generally don't consider the following:

• Preventing overflow when the tooltip is near a boundary (e.g. window), it will get cut off;
• Flipping to keep the tooltip visible in the viewport for the user;
• Keeping the tooltip with the reference element when inside a scrolling container;

Popper solves all of these key problems in an elegant, performant manner. It is a ~3 kB library that aims to provide a reliable and extensible positioning engine you can use to ensure all your popper elements are positioned in the right place. Why waste your time writing your own logic every time you are programming a tooltip? There are many edge cases that are easy to forget to consider, which is why we've done the hard work for you.

This library can position any pair of elements in your document without needing to alter the DOM in any way. It doesn't matter if your elements are not close to each other or are in two different scrolling containers, they will always end up in the right position.

Since we write UIs using powerful abstraction libraries such as React or Angular nowadays, you'll also be glad to know Popper can fully integrate with them and be a good citizen together with your other components. Check out react-popper for the official Popper wrapper for React.

Installation

1. Package Manager

# With Yarn
yarn add @popperjs/core@next

# With npm
npm i @popperjs/core@next

2. CDN

<script src="https://unpkg.com/@popperjs/core@next"></script>

3. Direct Download

Manually downloading the library is not recommended because you lose versioning management that the unpkg CDN or npm/Yarn provide.

You don't receive fix/feat updates easily and will lag behind the website documentation, among other issues, and this quickly becomes an unmaintainable way to manage dependencies.

Usage

Popper has the ability to work as a plug n' play library with all features included, as well as a tree-shakable library that minimizes bundle size if you import only what you need.

CDN

Generally, for CDN users, you'll be using the fully-featured umd file:

<script src="https://unpkg.com/@popperjs/core@next"></script>
<script>
  // Now the script is loaded, you can use the `Popper` class!
</script>

Importing features you need comes at the cost of extra HTTP requests which is usually not worth it.

Module Bundlers

For users of module bundlers like webpack or Rollup, you're going to want to take advantage of tree-shaking in your bundler. This comes at the cost of extra setup, but is worth it.

In your app, you can do the following:

// Import the core class
import Popper from '@popperjs/core';

// Import the features you need
import {
  computeStyles,
  applyStyles,
  detectOverflow,
  preventOverflow,
} from '@popperjs/core/lib/modifiers';

// Setup Popper's default modifiers for each new instance
Popper.defaultModifiers = [
  detectOverflow,
  preventOverflow,
  computeStyles,
  applyStyles,
];

Now you can use the Popper class with only the features you want. For instance, we aren't using the arrow, flip, or offset modifiers, because the current component, route, or our entire app does not need them. This lets us save on bundle size bytes for our users!

If you don't want to bother with tree-shaking and don't need bundle size cost advantages, you can import the fully featured esm file:

// All features included!
import Popper from '@popperjs/core/lib/popper';

Instantiation

Creating a popper instance is done by passing the reference element (such as a button), the popper element (such as a tooltip), and some options to the Popper constructor:

// Get your elements
const element = document.querySelector('#button');
const popper = document.querySelector('#tooltip');

// Let Popper do the magic!
new Popper(element, popper, { placement: 'right' });

Distribution targets

Popper is distributed in 3 different versions, in 3 different file formats.

The 3 file formats are:

• esm (works with import syntax — recommended)
• umd (works with <script> tags or RequireJS)
• cjs (works with require() syntax)

The 3 versions are:

• popper: includes all the modifiers (features) in one file (default for umd);
• popper-lite: includes only the minimum amount of modifiers to provide the basic functionality;
• popper-base: doesn't include any modifier, you must import them separately (default for esm and cjs);

Below you can find the size of each version, minified and compressed with the Brotli compression algorithm:

Hacking the library

If you want to play with the library, implement new features, fix a bug you found, or simply experiment with it, this section is for you!

First of all, make sure to have Yarn installed.

Install the development dependencies:

yarn install

And run the development environment:

yarn dev

Then, simply open one the development server web page:

# macOS and Linux
open localhost:5000

# Windows
start localhost:5000

From there, you can open any of the examples (.html files) to fiddle with them.

Now any change you will made to the source code, will be automatically compiled, you just need to refresh the page.

If the page is not working properly, try to go in "Developer Tools > Application > Clear storage" and click on "Clear site data".
To run the examples you need a browser with JavaScript modules via script tag support.

Test Suite

Popper is currently tested with unit tests, and functional tests. Both of them are run by Jest.

Unit Tests

The unit tests use JSDOM to provide a primitive document object API, they are used to ensure the utility functions behave as expected in isolation.

Functional Tests

The functional tests run with Puppeteer, to take advantage of a complete browser environment. They are currently running on Chromium, and Firefox.

You can run them with yarn test:functional, at the moment --watch mode is not supported due to a bug with jest-puppeteer.

The assertions are written in form of image snapshots, so that it's easy to assert for the correct Popper behavior without having to write a lot of offsets comparisons manually.

You can mark a *.test.js file to run in the Puppeteer environment by prepending a @jest-environment jest-environment-puppeteer JSDoc comment to the interested file.

Here's an example of a basic functional test:

/**
 * @jest-environment jest-environment-puppeteer
 * @flow
 */
import { screenshot } from '../utils/puppeteer.js';

it('should position the popper on the right', async () => {
  const page = await browser.newPage();
  await page.goto('http://localhost:5000/basic.html');

  expect(await screenshot(page)).toMatchImageSnapshot();
});

You can find the complete jest-puppeteer documentation here, and the jest-image-snapshot documentation here.