placement.js
v1.0.0-beta.5
Published
A tiny library for positioning overlays. Useful for tooltips, popovers etc.
Downloads
3,514
Readme
Placement.js
A tiny library for positioning overlays. Useful for tooltips, popovers etc.
Why? Positioning UI overlays like popovers and tooltips can be challenging. If you position them with CSS, then at some stage you are likely to run into problems with z-indices, parent overflows, or content going off the edge of the screen. JavaScript to the rescue!
Placement.js addresses a single use-case: positioning an overlay to one side of an anchor element, optimizing the placement depending on the size of the overlay:
- If the overlay is too big, it may flip to the other side if there is more room available.
- The dimensions of the overlay will be capped so that it will never go off-screen.
Small filesize is a priority for Placement.js so that it can be included in web components. For a more powerful, configurable library, check out Popper.js.
Installation
npm install placement.js --save
Usage
import placement from 'placement.js';
placement(
anchor: HTMLElement,
overlay: HTMLElement,
options?: Options
);
type Options = {
// The overlay placement relative to the anchor.
// Defaults to 'bottom'.
placement?:
| 'top'
| 'top-start'
| 'top-end'
| 'bottom'
| 'bottom-start'
| 'bottom-end'
| 'right'
| 'right-start'
| 'right-end'
| 'left'
| 'left-start'
| 'left-end',
// Whether or not the overlay can flip to the other side if there's more
// room available. Defaults to true.
flip?: boolean,
// Whether or not the overlay size should be capped to the available space.
// Defaults to true.
cap?: boolean,
};
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.