dom

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:
  • module:parsers.decodeHtmlEntities
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|Object|null}

Delegate DOM events. Uses event bubbling with closest() for events that bubble. Uses MutationObserver for non-bubbling events (focus, blur, mouseenter, mouseleave, etc.) to attach listeners directly to matching elements as they appear in the DOM.

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 | Object | null

For non-bubbling events the MutationObserver instance (with an added destroy() method that also removes the element listeners), for bubbling events a handle with destroy()/disconnect(), or null when MutationObserver is required but unavailable

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|null}

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

velocityWindow number <optional>
80

Time window (ms) over which flick velocity is measured

maxVelocity number <optional>
2

Cap on flick velocity magnitude (px/ms) to stop overshoot

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 | null

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:
  • module:parsers.encodeHtmlEntities
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) getFocusableElements(fromopt) → {Array.<HTMLElement>}

Returns all focusable elements from a given element or the document. Focusable elements are those that can be focused by the user, such as links, buttons, inputs, etc. Always use getVisibleFocusableElements instead of this function to ensure that only visible elements are returned, since only visible elements can be focused by the user.

Source:
See:
  • getVisibleFocusableElements
Parameters:
Name Type Attributes Default Description
from HTMLElement | Element | Document <optional>
document

The element to get the focusable elements from

Returns:
Type:
Array.<HTMLElement>

An array of focusable elements

Example
document.body.innerHTML = `
<div id="foo" tabindex="0">Foo</div>
<div id="bar" tabindex="-1">Bar</div>
<button id="baz">Baz</button>
<div id="qux" contenteditable="true">Qux</div>`
<a href="#quux" id="quux">Quux</a>

getFocusableElements() // => [<div id="foo" tabindex="0">Foo</div>, <button id="baz">Baz</button>, <div id="qux" contenteditable="true">Qux</div>, <a href="#quux" id="quux">Quux</a>]

(static) getHorizontalScrollState(element, thresholdopt) → {object}

Gets if the horizontal scroll has reached the start or end of the element.

Source:
Parameters:
Name Type Attributes Default Description
element HTMLElement

The element to check

threshold number <optional>
0

The threshold in pixels to consider the scroll as at the start or end

Returns:
Type:
object

An object with atStart and atEnd properties indicating if the scroll is at the start or end of the element

Example
const el = document.getElementById('foo')
const scrollState = getHorizontalScrollState(el, 10)
console.log(scrollState.atStart) // => true or false
console.log(scrollState.atEnd) // => true or false

(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) getTransitionDuration(element, propertyopt) → {number}

Returns the duration a single property will actually transition with, in milliseconds.

Unlike reading getTransitionDurations() by key, this resolves the all keyword: a transition: all 1s animates height too, it just isn't listed under that name. An untransitioned property reads as 0, which is also what transition: none gives you - so a reduced motion media query switching the transition off reads as "no animation".

Source:
Parameters:
Name Type Attributes Default Description
element HTMLElement

The element to get the transition duration from

property string <optional>
'all'

The CSS property to get the duration for

Returns:
Type:
number

The duration in milliseconds, 0 if the property is not transitioned

Example
getTransitionDuration(element, 'height') // 1000 if transition in CSS is set to 'height 1s'
getTransitionDuration(element, 'height') // 300 if transition in CSS is set to 'all 0.3s'
getTransitionDuration(element, 'height') // 0 if transition in CSS is set to 'opacity 1s'

(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) getVerticalScrollState(element, thresholdopt) → {object}

Gets if the vertical scroll has reached the start or end of the element.

Source:
Parameters:
Name Type Attributes Default Description
element HTMLElement

The element to check

threshold number <optional>
0

The threshold in pixels to consider the scroll as at the start or end

Returns:
Type:
object

An object with atStart and atEnd properties indicating if the scroll is at the start or end of the element

Example
const el = document.getElementById('foo')
const scrollState = getVerticalScrollState(el, 10)
console.log(scrollState.atStart) // => true or false
console.log(scrollState.atEnd) // => true or false

(static) getVisibleFocusableElements(fromopt, excludeSelectoropt) → {Array.<HTMLElement>}

Returns all visible focusable elements from a given element or the document.

Source:
See:
  • getFocusableElements
  • isVisible
Parameters:
Name Type Attributes Default Description
from HTMLElement | Element | Document <optional>
document

The element to get the focusable elements from

excludeSelector string <optional>

A selector to exclude elements from the result

Returns:
Type:
Array.<HTMLElement>

An array of visible focusable elements

Example
document.body.innerHTML = `
<div id="foo" tabindex="0">Foo</div>
<div id="bar" tabindex="-1">Bar</div>
<button id="baz" style="display: none;">Baz</button>
<div id="qux" contenteditable="true">Qux</div>`

getVisibleFocusableElements() // => [<div id="foo" tabindex="0">Foo</div>, <div id="qux" contenteditable="true">Qux</div>]
getVisibleFocusableElements(document.body, '#foo') // => [<div id="qux" contenteditable="true">Qux</div>]

(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) isHorizontalScrollVisible(element) → {boolean}

Checks if an element is overflowing horizontally used to check if the scrollbar is visible.

Source:
Parameters:
Name Type Description
element HTMLElement

The element to check

Returns:
Type:
boolean

True if the element is overflowing, false otherwise

Example
const el = document.getElementById('foo')
isHorizontalScrollVisible(el) // => true or false

(static) isScrollVisible(element) → {boolean}

Checks if an element is overflowing its container either vertically or horizontally used to check if the scrollbar is visible.

Source:
Parameters:
Name Type Description
element HTMLElement

The element to check

Returns:
Type:
boolean

True if the element is overflowing, false otherwise

Example
const el = document.getElementById('foo')
isScrollVisible(el) // => true or false

(static) isVerticalScrollVisible(element) → {boolean}

Checks if an element is overflowing its container used to check if the scrollbar is visible.

Source:
Parameters:
Name Type Description
element HTMLElement

The element to check

Returns:
Type:
boolean

True if the element is overflowing, false otherwise

Example
const el = document.getElementById('foo')
isVerticalScrollVisible(el) // => true or 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|Object|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 | Object | null

The MutationObserver instance (with an added destroy() method), a destroy/disconnect handle for bubbling delegated events, or null when MutationObserver is required but unavailable

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) readOptions(element, schema) → {object}

Read a set of typed options off an element's attributes.

Accepts the bare, kebab-case and data-* spellings of each option, with data-* winning when both are present, so a widget can be configured whichever way the markup author reaches for. Only the options actually present come back - absent ones are left out rather than defaulted, so the result merges cleanly over whatever defaults the caller holds.

Booleans follow HTML, not JavaScript: a bare attribute parses as an empty string and means "on", and only false and 0 mean off. Numbers that do not parse are dropped rather than coming back as NaN.

Source:
Parameters:
Name Type Description
element HTMLElement

The element to read the attributes from

schema object.<string, ('boolean'|'number'|'string')>

A map of camelCase option names to types

Returns:
Type:
object

The options present on the element, typed

Example
// <div data-page-step="25" exclusive label="FAQ">
readOptions(element, { pageStep: 'number', exclusive: 'boolean', label: 'string', muted: 'boolean' })
// => { pageStep: 25, exclusive: true, label: 'FAQ' }

(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, mouseopt) → {object|null}

Swipe event handler

Two points make the gesture - where the pointer went down and where it came up - so there is no pointermove listener running on every frame of every scroll down the page. The axis it travelled furthest along is the one reported, and a gesture as far down as across is neither.

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, timeThreshold and mouse

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.

mouse boolean <optional>
true

Whether a mouse drag counts as a swipe. Options object only. Turn it off on anything with selectable text, draggable images or links in it - reading a swipe from a mouse costs the page all three.

Returns:
Type:
object | null

The destroy method to remove the event listeners, or null without an element

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)
})

swipe(document.getElementById('foo'), { callback: onSwipe, threshold: 40, mouse: false })

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')