The Box

Utilities for working with DOM boxes.

How to use

Install the library via NPM:

npm install the-dom-box --save

Then use in your project like this:

import TheBox from 'the-dom-box';

// define some boxes
var my_element = document.getElementById('my_box');
var my_element_box = TheBox.getBox(my_element);
var viewport_box = TheBox.getBox('viewport');

// update box properties to reflext current size and position of input
my_element.style.left = '100px';
my_element_box.update();

// determine whether element can fit inside the viewport
TheBox.canContain(viewport_box, my_element_box); // -> true

// determine whether viewport can contain element with 100px empty space around it
my_element_box.pad(100);
TheBox.canContain(viewport_box, my_element_box); // -> false

Documentation

getBox

Checks for the type of input and returns appropriate Box object.

Parameters

• input [Any]

Returns Box instance of Box object

BoxProperties

Data object representing a box, with basic properties.

Box

Class representing an abstract Box.

constructor

Constructs generic Box object.

Parameters

• input [BoxProperties](default {})

pivot

Properties

• pivot object
  • pivot.left number Left position of Box's pivot.
  • pivot.top number Top position of Box's pivot.

set

Updates properties of the box

Parameters

• properties [BoxProperties](default {})

Returns BoxProperties

get

Gets current properties of the box.

Returns BoxProperties

update

Updates properties of the Box according to the Box's input. This doesn't really do anything in Generic Box. But it recalculates box properties for DOM element, collection, viewport, etc.

Returns BoxProperties

pad

Adds padding to the whole box.

Parameters

• padding [number] (optional, default 0)

padHorizontal

Adds padding to the left and right side of box.

Parameters

• padding [number] (optional, default 0)

padVertical

Adds padding to the top and bottom side of box.

Parameters

• padding [number] (optional, default 0)

moveTo

Move box to a specific location

Parameters

• left [number]
• top [number]

Returns Box

movePivotTo

Moves pivot of the box to a specific location, recalculates the other properties accordingly.

Parameters

• left [number]
• top [number]

Returns BoxProperties

moveBy

Moves the box by a distance.

Parameters

• horizontal [number]
• vertical [number]

Returns BoxProperties

resizeTo

Resizes the box to a specific size.

Parameters

• width
• height

Returns BoxProperties

resizeBy

Resizes the box by a specific value.

Parameters

• horizontal [number]
• vertical [number]

Returns BoxProperties

toString

Returns text representation of Box properties. Used for debugging.

Parameters

• pretty [boolean] If true, returns pretty formatted string. (optional, default false)

Returns string

ElementBox

Extends Box

Class representing Box of an Element.

CollectionBox

Extends Box

Class representing bounding Box around collection of elements. Accepts either HTMLCollection (e.g. getElementsByTagName()) or NodeList (e.g. querySelectorAll()).

DocumentBox

Extends Box

Class representing Box of whole document.

ViewportBox

Extends Box

Class representing Box of viewport.

get-distance

Returns horizontal, vertical, direct and pivot distance between two boxes.

Parameters

• a Box
• b Box

Returns {horizontal: number, vertical: number, pivot: number}

get-difference

Returns horizontal and vertical difference between two boxes. Positive values mean that boxes are apart, zero value means boxes are touching, negative value means boxes are overlapping.

Parameters

• a Box
• b Box

Returns {horizontal: number, vertical: number}

get-overlap

Returns box for an area where both boxes are overlapping. Returns null if boxes do not overlap.

Parameters

• a Box
• b Box

Returns (Box | null)

detect-overlap

Returns true if both boxes overlap at least partially.

Parameters

• a Box
• b Box

Returns boolean

get-pivot-angle

Returns angle between pivots of both boxes. Can be used with Angle JS to determine direction of one box relative to another.

Parameters

• a Box
• b Box
• use_radian [boolean] If true, returns result in radians, otherwise in degrees. (optional, default false)

Returns number

move-inside

Changes position of b to the closest position where it is completely inside a. If b can not fit a, it is positioned at top-left corner of a.

Parameters

• a Box
• b Box

contains

Returns true if box b is completely inside box a.

Parameters

• a Box
• b Box

Returns boolean

can-contain

Returns true if b can fit completely inside a.

Parameters

• a Box
• b Box

Returns boolean

can-coexist

Returns true if both b and c can fit completely inside a without changing their respective positions. Handy when deciding if boxes can be fully scrolled into a viewport.

Parameters

• a Box
• b Box
• c Box

Returns boolean

can-fit-around

Returns true if c can be positioned inside a so that it will not collide with b.

Parameters

• a Box
• b Box
• c Box

Returns boolean

find-closest

Returns box that is closest to a.

Parameters

• a Box
• boxes [Array<Box>] (optional, default [])
• property [string] Box's distance property (horizontal, vertical, direct or pivot) that will be used to evaluate ([see getDistance()](<{@link getDistance}>)). (optional, default 'direct')

Returns (Box | null)

fit-around

Changes positino of c so that it is positioned inside a without colliding with b. If it is not possible, position of c is unchanged. It will move the box to a new position closest to its original position.

Parameters

• a Box
• b Box
• c Box

shrink-to-fit

Adjusts size of b so that it fits a while keeping the original aspect ratio. Does nothing if b is smaller than a.

Parameters

• a Box
• b Box

align

Adjusts position of b so that it is aligned to a.

Parameters

• a Box
• b Box
• horizontal [string] 'left', 'right' or 'center'
• vertical [string] 'top', 'bottom' or 'center

touch

Move b so that it touches a from the outside.

Parameters

• a Box
• b Box
• horizontal [(null | string)] Either left or right.
• vertical [(null | string)] Either top or bottom.