placement.js

Placement.js

A tiny library for positioning overlays. Useful for tooltips, popovers etc.

Demo

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 { place } from 'placement.js';

place(
    anchor: HTMLElement,
    overlay: HTMLElement,
    options?: Options
);

type Options = {
    placement?: Placement // defaults to 'bottom'
};

type Placement =
    | 'top'
    | 'top-start'
    | 'top-end'
    | 'bottom'
    | 'bottom-start'
    | 'bottom-end'
    | 'right'
    | 'right-start'
    | 'right-end'
    | 'left'
    | 'left-start'
    | 'left-end';

Check out the demo to see it in action.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT

Changelog

[1.0.0-beta.3] - 2021-03-02

Added

• Placement.js now accounts for nesting within positioned elements. The overlay should be positioned correctly no matter where it is.
• If the overlay is a descendant of a scroll container, its position will be bounded automatically so it doesn't overflow the container.

Changed

• New API:
  • The module now exports the place function instead of a default export.
  • The order of the anchor and overlay arguments is swapped.
  • The side and align parameters have been combined into a single placement option.
• Smaller filesize. Now ~800 bytes!
• Updated demo – use the mouse to directly manipulate the anchor and overlay elements.

Removed

• Margins are no longer subtracted when positioning the overlay. Instead, add margins selectively depending on the [data-placement] attribute selector.
• Removed the fixed option.
• Removed the bound option.
• Removed the ability to specify Coordinates or Range as the anchor.