nanopop

Ultra Tiny, Opinionated Positioning Engine

Nanopop is an ultra-tiny positioning engine. Hold up, isn't there PopperJS? Yeah - and PopperJS is great! But there are tons of features that, in most cases, you just might not need. This library is less than a third of PopperJS.

When should I use Nanopop and not PopperJS?

1. Situations where you want full control over positioning, including handling events such as scrolling, and manual resizing.
2. Performance-critical cases with lots of elements [...] nanopop will only makes changes if you say so.
3. Poppers with minimal footprint such as drop-downs and tooltips which don't require that much configurability.
4. You might have some special needs about how your popper behaves. Index exposes a function for the sole purpose of positioning something, use it in your own library!

This library was originally part of pickr - now ported to TS with tests and a few updates / bug-fixes.

Heads up! This is the readme for v2 - if you're looking for the first version head over here (v1 is not maintained anymore).

Getting Started

Install via npm:

$ npm install nanopop

Install via yarn:

$ yarn add nanopop

Include directly via jsdelivr:

Using JavaScript Modules:

import {
    reposition,   // Core, stateless function to reposition an element
    createPopper, // Stateful function which keeps track of your configuration
    defaults,     // A subset of nanopops options used as default values
    version       // Current version
} from 'https://cdn.jsdelivr.net/npm/nanopop/lib/nanopop.min.mjs'

Index is fully tree-shakable! E.g. if you only use reposition you'll probably end up with less than 500B code!

Usage

reposition(
    /* reference: */ document.querySelector('.btn'),
    /* popper: */ document.querySelector('.dropdown'),
    /* We're using the default options */
);

⚠ The popper-element must have set position to fixed.

ℹ Because the default-container is document.documentElement you might have to increase the height of the html element to make room for your popper (e.g. html {height: 100vh;})

All options

…

Calling popper.update(...) or reposition(...) both returns a position-pair (For example te for Top-End) or null based on if it was possible to find a position for the popper without clipping it._

Tip: The returned position-pair is perfect for tool-tips to give them a little arrow!

Caveats

1. The popper-element must have position set to fixed.
2. If nanopop cannot find a position without clipping your popper it'll revert its top and left values - you can use css / js to handle this case.