Precisely Measure DOM Elements With The Mezr Library

Preview:

Description:

Mezr is a lightweight yet robust TypeScript library for precisely measuring and comparing DOM elements within the document. It currently provides nine useful API methods to handle width, height, offset, distance, rect, overflow, intersection, and more.

Install & Import:

# Yarn
$ yarn mezr
# NPM
$ npm i mezr

import { 
  getWidth, 
  getHeight,
  getOffset,
  getRect,
  getDistance,
  getIntersection,
  getOverflow,
  getContainingBlock,
  getOffsetContainer, 
} from 'mezr';

// OR
import { getWidth } from 'mezr/getWidth';
import { getHeight } from 'mezr/getHeight';
import { getOffset } from 'mezr/getOffset';
...

// Browser
<script src="dist/umd/mezr.js"></script>

How to use it:

1. Get the width of a DOM element in pixels using the getWidth() method. It can measure element boxes (content, padding, border, margin), documents, and viewports. A key benefit is accurately handling custom scrollbars.

// includes content + paddings + scrollbar + borders.
getWidth(element);
// or
getWidth(element, 'border');
// content only
getWidth(element, 'content');
// includes content + paddings
getWidth(element, 'padding');
// includes content + paddings + scrollbar
getWidth(element, 'scrollbar');
// includes content + paddings + scrollbar + borders + positive margins
getWidth(element, 'margin');

2. Get the height of a DOM element in pixels using the getHeight() method.

// includes content + paddings + scrollbar + borders.
getHeight(element);
// or
getHeight(element, 'border');
// content only
getHeight(element, 'content');
// includes content + paddings
getHeight(element, 'padding');
// includes content + paddings + scrollbar
getHeight(element, 'scrollbar');
// includes content + paddings + scrollbar + borders + positive margins
getHeight(element, 'margin');

3. Calculate the positional offset of an element in relation to another element, the window, or the document using the getOffset method. This will return an object with left and top offset in pixels.

// basic
getOffset(document);
getOffset(window);
getOffset(element);
// Advanced Usage
getOffset([element, 'content']);
getOffset([element, 'padding']);
getOffset([element, 'scrollbar']); 
getOffset([element, 'border']);
getOffset([element, 'margin']);
// offset from window.
getOffset(element, window);
// offset from another element
getOffset(element, otherElement);
getOffset([element, 'content'], [otherelement, 'margin']);

4. Get an element’s dimensions and offset using the getRect() method. It’s similar to JavaScript’s native getBoundingClientRect() API with some extra capabilities.

// basic
getRect(document);
getRect(window);
getRect(element);
// Advanced Usage
getRect([element, 'content']);
getRect([element, 'padding']);
getRect([element, 'scrollbar']); 
getRect([element, 'border']);
getRect([element, 'margin']);
// from window
getRect(element, window);
// from another element
getRect(element, otherElement);
getRect([element, 'content'], [otherelement, 'margin']);

5. Get the shortest distance between two elements using the getDistance() method.

// between A and B
getDistance(elementA, elementB);
// between A and Window
getDistance(element, window);
// Advanced Usage
getDistance([elementA, 'content'], [elementB, 'scrollbar']);

6. Get the intersection area of two or more elements usign the getIntersection() method.

// intersection area of two element
getIntersection(elementA, elementB);
// intersection area of element and window
getIntersection(element, window);
// Advanced Usage
getIntersection([elementA, 'content'], [elementB, 'scrollbar']);
// Multiple element
getIntersection(elementA, elementB, [elementC, 'scrollbar'], { left: 0, top: 0, width: 100, height: 100 });

7. Measure how much a target element overflows its container from each side using the getOverflow() method. This can be incredibly useful for responsive design, collision detection, and layout management in web development.

// how much elementA overflows elementB per each side.
getOverflow(elementA, elementB);
// how much element overflows window per each side.
getOverflow(element, window);
// Advanced Usages
getOverflow([elementA, 'content'], [elementB, 'scrollbar']);

8. Get the ancestor element that contains an element for relative sizing and positioning using the getContainingBlock() method.

// basic
getContainingBlock(element);
// if is a fixed element
getContainingBlock(element, { position: 'fixed' });
// skip "display:none"
getContainingBlock(element, { skipDisplayNone: true }});
// get element's containing block as if it were a child of document.body
getContainingBlock(element, { container: undefined }});

9. Get the parent reference element that establishes the coordinate system for positioning an element using the getOffsetContainer() method.

// basic
getOffsetContainer(element);
// if is a fixed element
getOffsetContainer(element, { position: 'fixed' });
// skip "display:none"
getOffsetContainer(element, { skipDisplayNone: true }});

Changelog:

v1.1.0 (11/25/2023)

• Add container option to getContainingBlock and getOffsetContainer methods.
• Allow providing node to getContainingBlock and getOffsetContainer methods.
• Update deps.