dom-align

What is dom-align?

The dom-align npm package is used for aligning DOM elements relative to each other. It provides utilities to position elements in relation to other elements or the viewport, ensuring they are properly aligned according to specified rules.

What are dom-align's main functionalities?

Aligning Elements

This feature allows you to align a source element relative to a target element. The `points` configuration specifies which points of the elements should be aligned, and the `offset` configuration allows you to add an offset to the alignment.

const align = require('dom-align');
const source = document.getElementById('source');
const target = document.getElementById('target');
const alignConfig = {
  points: ['tl', 'bl'], // Align top-left of source to bottom-left of target
  offset: [0, 10], // Offset by 10px vertically
};
align(source, target, alignConfig);

Viewport Alignment

This feature allows you to align an element relative to the viewport. The `points` configuration specifies which points of the element and the viewport should be aligned, and the `offset` configuration allows you to add an offset to the alignment.

const align = require('dom-align');
const source = document.getElementById('source');
const alignConfig = {
  points: ['tc', 'bc'], // Align top-center of source to bottom-center of viewport
  offset: [0, 20], // Offset by 20px vertically
};
align(source, window, alignConfig);

Other packages similar to dom-align

popper.js

Popper.js is a library used to position poppers (floating elements) in web applications. It provides more advanced positioning and flipping strategies compared to dom-align, making it suitable for complex tooltip and dropdown positioning.

tether

Tether is a JavaScript library for efficiently making an absolutely positioned element stay next to another element on the page. It offers similar functionality to dom-align but includes additional features like constraints to keep elements within the viewport.

position.js

Position.js is a lightweight library for positioning elements relative to other elements or the viewport. It offers basic alignment functionalities similar to dom-align but with a simpler API and fewer configuration options.

README

dom-align

---

align source html element with target html element flexibly.

Screenshot

Install

Feature

• support IE9+ chrome firefox
• support align points and offset
• support auto adjust according to visible area

Online Demo

• http://yiminghe.github.io/dom-align/

Usage

import domAlign from 'dom-align';

// use domAlign
// sourceNode's initial style should be position:absolute;left:-9999px;top:-9999px;

const alignConfig = {
  points: ['tl', 'tr'],        // align top left point of sourceNode with top right point of targetNode
  offset: [10, 20],            // the offset sourceNode by 10px in x and 20px in y,
  targetOffset: ['30%','40%'], // the offset targetNode by 30% of targetNode width in x and 40% of targetNode height in y,
  overflow: { adjustX: true, adjustY: true }, // auto adjust position when sourceNode is overflowed
};

domAlign(sourceNode, targetNode, alignConfig);

API

void domAlign(source: HTMLElement, target: HTMLElement, alignConfig: Object):Function

alignConfig object details

name	type	description
points	String[2]	move point of source node to align with point of target node, such as ['tr','cc'], align top right point of source node with center point of target node. point can be 't'(top), 'b'(bottom), 'c'(center), 'l'(left), 'r'(right)
offset	Number[2]	offset source node by offset[0] in x and offset[1] in y. If offset contains percentage string value, it is relative to sourceNode region.
targetOffset	Number[2]	offset target node by offset[0] in x and offset[1] in y. If targetOffset contains percentage string value, it is relative to targetNode region.
overflow	Object: `{ adjustX: boolean, adjustY: boolean, alwaysByViewport:boolean }`	if adjustX field is true, then will adjust source node in x direction if source node is invisible. if adjustY field is true, then will adjust source node in y direction if source node is invisible. if alwaysByViewport is true, the it will adjust if node is not inside viewport
useCssRight	Boolean	whether use css right instead of left to position
useCssBottom	Boolean	whether use css bottom instead of top to position
useCssTransform	Boolean	whether use css transform instead of left/top/right/bottom to position if browser supports. Defaults to false.

Development

npm install
npm start

Example

http://localhost:8020/examples/

Test Case

npm test
npm run chrome-test

Coverage

npm run coverage

open coverage/ dir

License

dom-align is released under the MIT license.