Ultra Tiny, Opinionated Positioning Engine
Index 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?
- Situations where you want full control over positioning, including handling events such as scrolling, and manual resizing.
- Performance-critical cases with lots of elements [...] nanopop will only makes changes if you say so.
- Poppers with minimal footprint such as drop-downs and tooltips which don't require that much configurability.
- 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 nanopopInstall via yarn:
$ yarn add nanopopInclude directly via jsdelivr:
<script src="https://cdn.jsdelivr.net/npm/nanopop/dist/nanopop.umd.js"></script>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 userepositionyou'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 setpositiontofixed.
โน Because the default-containerisdocument.documentElementyou might have to increase theheightof thehtmlelement to make room for your popper (e.g.html {height: 100vh;})
All options
import {reposition, createPopper} from 'nanopop';
// Using a object and reposition directly
const nanopop = reposition(reference, popper, {
// The DOMRect of the container, it used the html-element as default.
// You could also create your own boundary using a custon DOMRect (https://developer.mozilla.org/en-US/docs/Web/API/DOMRect)!
container: document.documentElement.getBoundingClientRect(),
// Optional arrow element that is positioned between the popper and the reference element.
arrow: undefined,
// Margin between the popper element and the reference
margin: 8,
// Minimum space between the popper and the container
padding: 0,
// Preferred position, any combination of [top|right|bottom|left]-[start|middle|end] is valid.
// 'middle' is used as default-variant if you leave it out.
position: 'bottom-middle',
// In case the variant-part (start, middle or end) cannot be applied you can specify what (and if)
// should be tried next.
variantFlipOrder: {
start: 'sme', // In case of -start try 'start' first, if that fails 'middle' and 'end' if both doesn't work.
middle: 'mse',
end: 'ems'
},
// The same as variantFlipOrder, but if all variants fail you might want to try other positions.
positionFlipOrder: {
top: 'tbrl', // Try 'top' first, 'bottom' second, 'right' third and 'left' as latest position.
right: 'rltb',
bottom: 'btrl',
left: 'lrbt'
}
});
/**
* Using the createPopper function to create a stateful wrapper
*
* Correct ways of calling it are:
* createPopper(reference: HTMLElement, popper: HTMLElement, options?: NanoPopOptions)
* createPopper(options?: NanoPopOptions)
* โ If you omit options entierly you'll have to set both the reference and the popper later when calling .update!
*/
const popper = createPopper({...});
popper.update(); // You can pass an object to update which will get merged with the existing config.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
- The popper-element must have
positionset tofixed. - If nanopop cannot find a position without clipping your popper it'll revert its
topandleftvalues - you can use css / js to handle this case.