dom

Description#

A set of utilities to interact with the DOM, event listeners and similar low level tasks. For a more structured API (jQuery like) consider DOMtastic.

import { ... } from "@acanto/core-dom";

API#

escape#

See: https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector#Escaping_special_characters

Escape colons to allow use class names as .module:block__element

Parameters#

selector string

Returns string

\$

Sizzle/jQuery like DOM nodes shortcut for document.querySelector To avoid an extra function call we inline the above escape

Parameters#

selector string DOM selector
parent HTMLElement? It falls back to window.document

Examples#

Basic DOM selection

const $container = $(".my-section:");
const $el = $("[data-some-attr]", $container);

Returns HTMLElement

\$\$#

Sizzle/jQuery like DOM nodes shortcut for document.querySelectorAll To avoid an extra function call we inline the above escape

Parameters#

selector string DOM selector
parent HTMLElement? It falls back to window.document

Returns NodeList

forEach#

For each, iterate through a NodeList of HTMLElements

Parameters#

nodes NodeList DOM nodes collection
callback function (HTMLElement, number): any
scope Object?

\$each#

Each shortcut, iterate through a NodeList of HTMLElements retrieved with the given selector (and optionally a parent container passed as thrid arguement)

Parameters#

selector string DOM selector
callback function (HTMLElement, number): any
parent HTMLElement? It falls back to window.document
scope Object?

toArray#

Node list to array

Parameters#

nodeList (NodeList | HTMLFormControlsCollection)

Returns (Array<HTMLElement> | Array<HTMLFormElement>)

setVendorCSS#

Set vendor CSS rule

Parameters#

element HTMLElement A single HTMLElement
prop string CSS rule proerty
value (string | number | boolean) The CSS value to set, it will be automatically vendor prefixed

isNodeList#

Is node list

Parameters#

nodes any The object to check

Returns boolean

on#

Shortcut for addEventListener

Parameters#

el (Window | Document | HTMLElement)
type string
handler EventListener
options (AddEventListenerOptions | boolean) (optional, default false)

off#

Shortcut for removeEventListener

Parameters#

el (Window | Document | HTMLElement)
type string
handler EventListener
options (EventListenerOptions | boolean) (optional, default false)

once#

One shot listener, it addEventListener and removes it first time is called with removeEventListener

Parameters#

el (Window | Document | HTMLElement)
type string
handler EventListener
options (EventListenerOptions | boolean) (optional, default false)

createElement#

Shortcut for document.createElement, allowing to to create an HTML element with a given className directly (a very common use case)

Parameters#

type string
className string?

Returns HTMLElement

isHidden#

Is element hidden?

Parameters#

el HTMLElement?

Returns boolean

siblings#

See: @glidejs/glide/src/utils/dom (source)

Finds siblings nodes of the passed node.

Parameters#

node Element

Returns Array

exists#

See: @glidejs/glide/src/utils/dom (source)

Checks if passed node exist and is a valid element.

Parameters#

node Element

Returns Boolean

getDataAttr#

Get data attribute

Parameters#

element HTMLElement
attribute string The name of the data-{attr}

Returns (string | null)

setDataAttr#

Set data attribute

Parameters#

element Element
attribute string The name of the data-{attr}
value (string | number | null)? The value to set, null or undefined will remove the attribute

activeEvents#

Listen: events delegation system

From: https://github.com/cferdinandi/events https://github.com/cferdinandi/events/blob/master/src/js/events/events.js

activeEvents#

Active events

ListenEvent#

Type: Object

Properties#

selector string

getIndex#

Get the index for the listener

Parameters#

arr Array
selector string
callback

Returns number The index of the listener

getRunTarget#

Check if the listener callback should run or not

Parameters#

target Element The event.target
selector (string | window | Document | Element) The selector/element to check the target against

Returns (window | Document | Element | false) If not false, run listener and pass the targeted element to use in the callback

eventHandler#

Handle listeners after event fires

Parameters#

event Event The event

event#

Type: Element

listen#

Listen an event

Parameters#

types string The event type or types (comma separated)
selector string The selector to run the event on
callback

unlisten#

Stop listening for an event

Parameters#

types string The event type or types (comma separated)
selector string The selector to remove the event from
callback Function The function to remove

listenOnce#

Listen an event, and automatically unlisten it after it's first run

Parameters#

types string The event type or types (comma separated)
selector string The selector to run the event on
callback Function The function to run when the event fires

getListeners#

Get an immutable copy of all active event listeners

Returns Object Active event listeners

listenLoaded#

See: https://mathiasbynens.be/notes/settimeout-onload

Fires a callback when the DOM content is loaded

Parameters#

handler EventHandlerNonNull

listenResize#

Listen window resize event using lodash's debounce

Parameters#

handler EventHandlerNonNull
debounceOptions

Returns Function An automatic unbinding function to run to deregister the listener upon call

unbinder#

Unbind the previously attached scroll handler

unbinder#

Unbind the previously attached scroll handler

listenScroll#

Listen window scroll event using lodash's debounce

Parameters#

handler EventHandlerNonNull
debounceOptions

throttle#

See: https://github.com/Mobius1/Rangeable/

Throttle for resize / scroll

Parameters#

fn Function
limit Number
context Object

Returns Function

emitEvent#

Emit event (use only if the targeted browser supports CustomEvents)

Parameters#

type string (optional, default "customEvent")
detail Object (optional, default {})

getHeight#

Get element height

Parameters#

element HTMLElement

Returns number

getOffset#

Get an element's distance from the top and left of the Document.

Parameters#

elem HTMLElement The HTML node element

Returns {top: number, left: number} Distance from the top and left in pixels

getOffsetTop#

See: https://vanillajstoolkit.com/helpers/getoffsettop/

Get an element's distance from the top of the Document.

Parameters#

elem HTMLElement The HTML node element

Returns number Distance from the top in pixels

getDocumentHeight#

See: https://github.com/cferdinandi/smooth-scroll (credits)

Determine the document's height

Returns number

getScrollbarWidth#

Get scrollbar's current width

Parameters#

element HTMLElement?

Returns number

isTotallyScrolled#

Is element totally scrolled

Parameters#

el HTMLElement?

Returns boolean

isInViewport#

Determine if an element is in the viewport

Parameters#

elem Element The element

Returns boolean Returns true if element is in the viewport