dom

Source:

Members

(static, constant) onDrag

Alias for drag

Deprecated:
  • Use drag instead
Source:
See:
  • drag

(static, constant) onSwipe

Alias for swipe

Deprecated:
  • Use swipe instead
Source:
See:
  • swipe

Methods

(static) addListenerForEvents(elements, events, handler, optionsopt)

Adds one listener to multiple events

Source:
Parameters:
Name Type Attributes Description
elements string | HTMLElement | NodeList

The elements or a selector for elements to add the event listeners to
events string | Array.<string>

The event types to add the event listeners for, like click mouseenter
handler function

The handler to call when the event is triggered.
options object <optional>

The options to pass to the event listeners
Example
addListenerForEvents('.foo', 'click mouseenter', (e) => { console.log(e.type) })

(static) css(element, styles, transform)

Sets element styles from passed object of styles. Can also transform dash-case to camelCase for CSS properties

Source:
Parameters:
Name Type Description
element HTMLElement

The element to set styles on
styles object

The object of styles to set
transform boolean

Whether to transform dash-case to camelCase for CSS properties
Example
css(document.getElementById('foo'), { 'background-color': 'red', 'font-size': '16px' }, true) // => sets background-color and font-size
css(document.getElementById('foo'), { backgroundColor: 'red', fontSize: '16px' }) // => sets background-color and font-size

(static) cssTimeToMilliseconds(duration) → {number}

Converts a duration string to milliseconds integer

Source:
Parameters:
Name Type Description
duration string

The duration string to convert, e.g. '1s', '100ms', '0.5s'
Returns:
Type:
number

The duration in milliseconds

Example
convertToMilliseconds('1s') // 1000
convertToMilliseconds('100ms') // 100
convertToMilliseconds('0.5s') // 500
convertToMilliseconds('0.5') // 0
convertToMilliseconds('foo') // 0

(static) decodeHTML(html) → {string}

Decodes HTML entities in a string using the browser's DOMParser. If the DOMParser is not available, it uses a regular expression to decode the basic entities.

Source:
See:
Parameters:
Name Type Description
html string

The HTML string to decode
Returns:
Type:
string

The decoded HTML string

Example
decodeHTML('&lt;div&gt;foo&lt;/div&gt;') // => '<div>foo</div>'
decodeHTML('&lt;div&gt;foo&lt;/div&gt;&lt;div&gt;bar&lt;/div&gt;') // => '<div>foo</div><div>bar</div>'

(static) delegateEvent(selector, eventType, handler) → {MutationObserver|null}

Delegate DOM events using MutationObserver with a fallback to document.addEventListener

Source:
Parameters:
Name Type Description
selector string

The selector to select the elements to delegate the event to
eventType string

The event type to delegate, like click
handler function

The handler to call when the event is triggered.
Returns:
Type:
MutationObserver | null

The MutationObserver instance

Example
delegateEvent('.foo', 'click', (e, target) => {
console.log('Clicked on', target)
})

(static) detachElement(element)

Detaches an element from the DOM and returns it

Source:
Parameters:
Name Type Description
element HTMLElement

The element to detach
Example
detachElement(element)
// => element
console.log(element.parentNode) // => null

(static) drag(element, opts) → {object}

Drag event handler

Source:
Parameters:
Name Type Description
element HTMLElement

The element to listen for drag gestures on
opts object | function

The options object or the callback to call when a drag gesture is detected

Name Type Attributes Default Description
inertia boolean <optional>
 false

Whether to enable inertia
bounce boolean <optional>
 false

Whether to enable bounce when inertia is enabled
friction number <optional>
 0.9

The friction to apply when inertia is enabled
bounceFactor number <optional>
 0.2

The bounce factor to apply when bounce is enabled
preventDefaultTouch boolean <optional>
 true

Whether to prevent the default touch behavior
callback function <optional>

The callback to call when a drag gesture is detected
Returns:
Type:
object

The destroy method to remove the event listeners

Example
drag(document.getElementById('foo'), (e) => {
 console.log(e.x)
 console.log(e.y)
 console.log(e.relativeX)
 console.log(e.relativeY)
 console.log(e.xPercentage)
 console.log(e.yPercentage)
 console.log(e.velocityX)
 console.log(e.velocityY)
 console.log(e.prevX)
 console.log(e.prevY)
})

element.addEventListener('drag', (e) => { ... })
element.addEventListener('dragstart', (e) => { ... })
element.addEventListener('dragend', (e) => { ... })
element.addEventListener('draginertia', (e) => { ... })
element.addEventListener('draginertiaend', (e) => { ... })

(static) encodeHTML(html) → {string}

Encodes HTML entities in a string using the browser's DOMParser. If the DOMParser is not available, it uses a regular expression to encode the basic entities.

Source:
See:
Parameters:
Name Type Description
html string

The HTML string to encode
Returns:
Type:
string

The encoded HTML string

Example
encodeHTML('<div>foo</div>') // => '&lt;div&gt;foo&lt;/div&gt;'
encodeHTML('<div>foo</div><div>bar</div>') // => '&lt;div&gt;foo&lt;/div&gt;&lt;div&gt;bar&lt;/div&gt;'

(static) getTableData(selector, headers, rowSelectoropt, cellSelectoropt) → {Array.<object>}

Gets table data from a table element, a simple regular table element, or a table like structure. Useful for scraping data.

Source:
Parameters:
Name Type Attributes Default Description
selector string

The selector to select the table element
headers Array.<string> | string | null

The headers to use for the data. If 'auto' is passed, the row containing th or the first row will be used as headers
rowSelector string <optional>
 'tr'

The selector to select the rows
cellSelector string <optional>
 'td'

The selector to select the cells
Returns:
Type:
Array.<object>

An array of objects with the properties as keys and the cell values as values

Example
document.body.innerHTML = `
<table id="table">
 <thead>
  <tr>
  <th>Foo</th>
 <th>Bar</th>
</tr>
</thead>
<tbody>
<tr>
<td>Foo 1</td>
<td>Bar 1</td>
</tr>  
<tr>
<td>Foo 2</td>
<td>Bar 2</td>
</tr>
</tbody>
</table>`

getTableData('#table', ['foo', 'bar'])
// => [
//  { foo: 'Foo 1', bar: 'Bar 1' },
//  { foo: 'Foo 2', bar: 'Bar 2' }
// ]

(static) getTransitionDurations(element) → {object.<string, number>}

Returns a map of transition properties and durations

Source:
Parameters:
Name Type Description
element HTMLElement

The element to get the transition properties and durations from
Returns:
Type:
object.<string, number>

A map of transition properties and durations

Example
getTransitionDurations(element) // { height: 1000 } if transition in CSS is set to 'height 1s'
getTransitionDurations(element) // { height: 500, opacity: 1000 } if transition in CSS is set to 'height 0.5s, opacity 1s'

(static) insertBeforeElement(targetElement, newElement)

Inserts an element before another element

Source:
Parameters:
Name Type Description
targetElement HTMLElement

The element to insert before
newElement HTMLElement

The element to insert
Example
const target = document.getElementById('target')
const newElement = document.createElement('div')
newElement.id = 'newElement'
insertBeforeElement(target, newElement)
// <div id="newElement"></div>
// <div id="target"></div>

(static) isEmptyElement(element)

Checks if an element is empty

Source:
Parameters:
Name Type Description
element HTMLElement
Returns:

boolean

Example
document.body.innerHTML = `
 <div id="empty-element"></div>
 <div id="non-empty-element1">foo</div>
 <div id="non-empty-element2"><br></div>`

isEmptyElement(document.getElementById('empty-element')) // => true
isEmptyElement(document.getElementById('non-empty-element1')) // => false
isEmptyElement(document.getElementById('non-empty-element2')) // => false

(static) isVisible(element) → {boolean}

If provided element is visible. Checks if the element is not visibility hidden or display none, has no opacity, and has a width and height.

Source:
Parameters:
Name Type Description
element HTMLElement

The element to check
Returns:
Type:
boolean

True if the element is visible, false otherwise

Example
isVisible(document.getElementById('foo'))

(static) loadImage(src, callbackopt)

Loads an image form a provided source url and calls a callback when it's loaded

Source:
Parameters:
Name Type Attributes Description
src string

The source url of the image
callback function <optional>

The callback to call when the image is loaded
Example
loadImage('https://example.com/image.png', () => {
 console.log('Image loaded')
})

(static) matchesAll(elements, selector) → {boolean}

Check a list of elements if all of them matches a selector

Source:
Parameters:
Name Type Description
elements Array.<HTMLElement> | NodeList | HTMLElement

The elements to check
selector string

The selector to check
Returns:
Type:
boolean

True if all of the elements matches the selector, false otherwise

Example
document.body.innerHTML = `
<div id="foo"></div>
<div id="bar"></div>
<div id="baz"></div>`

matchesAll(document.querySelectorAll('div'), 'div') // => true
matchesAll(document.querySelectorAll('div'), '#foo') // => false

(static) matchesAny(elements, selector) → {boolean}

Check a list of elements if any of them matches a selector

Source:
Parameters:
Name Type Description
elements Array.<HTMLElement> | NodeList | HTMLElement

The elements to check
selector string

The selector to check
Returns:
Type:
boolean

True if any of the elements matches the selector, false otherwise

Example
document.body.innerHTML = `
<div id="foo"></div>
<div id="bar"></div>
<div id="baz"></div>`

matchesAny(document.querySelectorAll('div'), '#foo') // => true
matchesAny(document.querySelectorAll('div'), '#qux') // => false

(static) on(selector, eventTypeOrHandler, handleropt) → {MutationObserver|null}

Run a handler on selected elements and on elements added to the DOM with the same selector as a MutationObserver abstraction, or use it to delegate events as a delegateEvent alias

Source:
See:
  • delegateEvent
Parameters:
Name Type Attributes Description
selector string

The selector to select the elements to run the handler on
eventTypeOrHandler string | function

The event type to delegate, like click, or the handler to call on every element
handler function <optional>

The handler to call when the event is triggered.
Returns:
Type:
MutationObserver | null

The MutationObserver instance

Example
on('.foo', (el) => {
console.log('Element', el, 'added to the DOM')
})

on('.foo', 'click', (e, target) => {
console.log('Clicked on', target)
})

(static) parseDOM(html, allChildrenopt) → {Node}

Parses HTML string to a DOM Node

Source:
Parameters:
Name Type Attributes Default Description
html string

The HTML string to parse
allChildren boolean <optional>
 false

If true, all children of the body will be returned, otherwise only the first child
Returns:
Type:
Node

The parsed DOM Node

Example
parseDOM('<div>foo</div>') // => <div>foo</div>
parseDOM('<div>foo</div><div>bar</div>', true) // => NodeList(2) [div, div]
parseDOM(document.getElementById('foo')) // => <div id="foo"></div>
parseDOM(document.querySelectorAll('div')) // => NodeList(2) [div, div]

(static) proportionalParentCoverResize(elements, ratioopt, offsetopt)

Resizes an element to cover its parent element while maintaining the aspect ratio

Source:
Parameters:
Name Type Attributes Default Description
elements string | HTMLElement | NodeList

The elements or a selector for elements to resize
ratio number <optional>
 1

The ratio to maintain
offset number <optional>
 0

An offset to add to the parent element's width and height
Example
proportionalParentCoverResize('.foo', 16/9, 10)

(static) query(selector, fromopt) → {Array.<Element>|NodeList}

Queries the DOM for elements and returns them. Substitutes for document.querySelectorAll(selector) and JQuery's $(selector)

Source:
Parameters:
Name Type Attributes Default Description
selector string | HTMLElement | Element | Array.<(HTMLElement|Element)> | NodeList

The selector to select elements
from HTMLElement | Element <optional>
 document

The element to query from
Returns:
Type:
Array.<Element> | NodeList
Example
document.body.innerHTML = `
<div id="foo"></div>
<div id="bar"></div>
<div id="baz"></div>`

query('#foo') // => [<div id="foo"></div>]
query(document.getElementById('foo')) // => [<div id="foo"></div>]
query('div') // => [<div id="foo"></div>, <div id="bar"></div>, <div id="baz"></div>]

(static) querySingle(selector, fromopt) → {HTMLElement|Element}

Queries the DOM for a single element and returns it. Substitutes for document.querySelector(selector) and JQuery's $(selector).first()

Source:
Parameters:
Name Type Attributes Default Description
selector string | HTMLElement | Element | Array.<(HTMLElement|Element)> | NodeList

The selector to select an element
from HTMLElement | Element <optional>
 document

The element to query from
Returns:
Type:
HTMLElement | Element
Example
document.body.innerHTML = `
<div id="foo"></div>
<div id="bar"></div>
<div id="baz"></div>`

querySingle('#foo') // => <div id="foo"></div>
querySingle(document.getElementById('foo')) // => <div id="foo"></div>
querySingle(document.querySelector('#foo')) // => <div id="foo"></div>

(static) remove(selector, fromopt)

Removes all elements matching a selector from the DOM

Source:
Parameters:
Name Type Attributes Default Description
selector string | HTMLElement | Element

The selector to select elements to remove
from HTMLElement | Element <optional>
 document

The element to remove elements from
Example
document.body.innerHTML = `
<div id="foo"></div>
<div id="bar"></div>
<div id="baz"></div>`
`
remove('#foo, #bar') // => removes #foo and #bar

(static) removeListenerForEvents(elements, events, handler, optionsopt)

Removes one listener from multiple registered events

Source:
Parameters:
Name Type Attributes Description
elements string | HTMLElement | NodeList

The elements or a selector for elements to remove the event listeners from
events string | Array.<string>

The event types to remove the event listeners for, like click mouseenter
handler function

The handler to remove
options object <optional>

The options to pass to the event listeners
Example
removeListenerForEvents('.foo', 'click mouseenter', (e) => { console.log(e.type) })

(static) swipe(element, callback, thresholdopt, timeThresholdopt) → {object}

Swipe event handler

Source:
Parameters:
Name Type Attributes Default Description
element HTMLElement

The element to listen for swipe gestures on
callback object | function

The callback to call when a swipe gesture is detected or the options object with the callback, threshold, and timeThreshold
threshold number <optional>
 150

The threshold in pixels to trigger the callback.
timeThreshold number <optional>
 0

The threshold in milliseconds to trigger the callback. Defaults to 0, which means the callback will be called regardless of the time it took to swipe.
Returns:
Type:
object

The destroy method to remove the event listeners

Example
swipe(document.getElementById('foo'), (e) => {
 console.log(e.direction)
 console.log(e.deltaX)
 console.log(e.deltaY)
 console.log(e.startX)
 console.log(e.startY)
 console.log(e.endX)
 console.log(e.endY)
 console.log(e.threshold)
 console.log(e.type)
 console.log(e.target)
 console.log(e.horizontal)
 console.log(e.vertical)
 console.log(e.horizontalDirection)
 console.log(e.verticalDirection)
 console.log(e.timeElapsed)
 console.log(e.timeThreshold)
})

element.addEventListener('swipe', (e) => { ... })
element.addEventListener('swipestart', (e) => { ... })
element.addEventListener('swipeend', (e) => { ... })

(static) toggleAttributeValue(element, attribute, on, off)

Toggles an attribute value on an element

Source:
Parameters:
Name Type Description
element HTMLElement

The element to toggle the attribute on
attribute string

The attribute to toggle
on string

Default: 'true'
off string

Default: 'false'
Example
toggleAttributeValue(element, 'aria-expanded', 'true', 'false')
toggleAttributeValue(element, 'aria-expanded')