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:
; // define some boxesvar my_element = document;var my_element_box = TheBox;var viewport_box = TheBox; // update box properties to reflext current size and position of inputmy_elementstyleleft = '100px';my_element_box; // determine whether element can fit inside the viewportTheBox; // -> true // determine whether viewport can contain element with 100px empty space around itmy_element_box;TheBox; // -> 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
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, default0
)
padHorizontal
Adds padding to the left and right side of box.
Parameters
padding
[number] (optional, default0
)
padVertical
Adds padding to the top and bottom side of box.
Parameters
padding
[number] (optional, default0
)
moveTo
Move box to a specific location
Parameters
Returns Box
movePivotTo
Moves pivot of the box to a specific location, recalculates the other properties accordingly.
Parameters
Returns BoxProperties
moveBy
Moves the box by a distance.
Parameters
Returns BoxProperties
resizeTo
Resizes the box to a specific size.
Parameters
width
height
Returns BoxProperties
resizeBy
Resizes the box by a specific value.
Parameters
Returns BoxProperties
toString
Returns text representation of Box properties. Used for debugging.
Parameters
pretty
[boolean] Iftrue
, returns pretty formatted string. (optional, defaultfalse
)
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
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
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
Returns (Box | null)
detect-overlap
Returns true if both boxes overlap at least partially.
Parameters
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
Boxb
Boxuse_radian
[boolean] Iftrue
, returns result in radians, otherwise in degrees. (optional, defaultfalse
)
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
contains
Returns true
if box b
is completely inside box a
.
Parameters
Returns boolean
can-contain
Returns true
if b
can fit completely inside a
.
Parameters
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
Returns boolean
can-fit-around
Returns true
if c
can be positioned inside a
so that it will not collide with b
.
Parameters
Returns boolean
find-closest
Returns box that is closest to a
.
Parameters
a
Boxboxes
[Array<Box>] (optional, default[]
)property
[string] Box's distance property (horizontal
,vertical
,direct
orpivot
) that will be used to evaluate ([seegetDistance()
](<{@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
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
align
Adjusts position of b
so that it is aligned to a
.
Parameters
a
Boxb
Boxhorizontal
[string] 'left', 'right' or 'center'vertical
[string] 'top', 'bottom' or 'center
touch
Move b
so that it touches a
from the outside.
Parameters