Okiba / dom

Utilities to work with dom elements and selectors

__

Installation

npm i --save @okiba/dom

Or import it directly in the browser

<script type="module" src="https://unpkg.com/@okiba/dom/index.js"></script>

Usage

import dom from '@okiba/dom'

Untranspiled code 🛑

Okiba Core packages are not transpiled, so don't forget to transpile them with your favourite bundler. For example, using Babel with Webpack, you should prevent imports from okiba to be excluded from transpilation, like follows:

{
  test: /\.js$/,
  exclude: /node_modules\/(?!(@okiba)\/).*/,
  use: {
    loader: 'babel-loader',
    options: {
      presets: ['@babel/preset-env']
    }
  }
}

byId(id)

Selects a DOM Element with a certain id

import {byId} from '@okiba/dom'
const apple = byId('apple')
console.log(apple) // [div.apple]

Arguments

+ id: String

DOM id you are looking for

Returns

Element A DOM Element matching id

qs(selector, element)

Selects a DOM Element, scoped to element

import {qs} from '@okiba/dom'
const pear = qs('.pear')
console.log(pear) // [div.pear]

Arguments

+ selector: String

DOM Selector (tag, class, id, anything that can be passed to querySelector API)

+ element: Element | optional - default: document

DOM Element to scope the selection query, only childs of that element will be tageted

Returns

Element A DOM Element matching selector

qsa(selector, element)

Selects an array of DOM Elements, scoped to element

import {qsa} from '@okiba/dom'
const fruits = qsa('.fruit')
console.log(fruits) // [div.fruit, div.fruit]

Arguments

+ selector: String

DOM Selector (tag, class, id, anything that can be passed to querySelector API)

+ element: Element | optional - default: document

DOM Element to scope the selection query, only childs of that element will be tageted

Returns

Array.<Element> An array of DOM elements matching selector

on(window, type, handler)

Attaches an event listener to a DOM Element, or an array of.

import {qsa, on} from '@okiba/dom'
const buttons = qsa('.button')

on(buttons, 'click', onClick)
on(buttons, ['mouseenter', 'mouseleve'], onMouseChange)

// adds `onClick` to 'click' and `onMouseChange` to both 'mouseenter' and 'mouseleave'
on(buttons, ['click', mouseenter', 'mouseleve'], [onClick, onMouseChange])

Arguments

+ window: Element or Array.<Element> | optional

source the element which will trigger the event

+ type: String or Array.<String>

the event name to bind. Or an array of

+ handler: function or Array.<function()>

the callback to be fired at the event. If an array is supplied the handlers will be bound in order, if there are less handlers than event types, the last handler is bound to all remaining events.

Returns

Boolean Success of the binding

off(window, type, handler)

Detached an event listener from a DOM Element, or an array of.

import {qs, off} from '@okiba/dom'
const button = qs('.button')

button.addEventListener('click', onButtonClick)
// or okiba's `on` on(button, 'click')

off(button, 'click', onButtonClick)

// removes `onMouseChange` from both 'mouseenter' and 'mouseleave'
off(buttons, ['mouseenter', 'mouseleve'], onMouseChange)

// removes `onClick` from 'click' and `onMouseChange` from both 'mouseenter' and 'mouseleave'
off(buttons, ['click', mouseenter', 'mouseleve'], [onClick, onMouseChange])

Arguments

+ window: Element or Array.<Element> | optional

source Element which will trigger the event

+ type: String or Array.<String>

Event name to unbind. Or an array of

+ handler: function or Array.<function()>

Callback bound to the event. If an array is supplied the handlers will be unbound in order, if there are less handlers than event types, the last handler is unbound from all remaining events.

Returns

Boolean Success of the unbinding

eventCoords(DOM)

Read mouse and touch position in the same way

import {eventCoords, on} from '@okiba/dom'
on(window, ['mousemove', 'touchmove'], onMove)

function onMove(e){
 const coords = eventCoords(e)
 console.log(coords)
}

Arguments

+ DOM: Event

Event

Returns

Object Event position coordinates (clientX and ClientY)

offset(el)

Gets top and left offsets of an element

import {qs, offset} from '@okiba/dom'
const el = qs('.something')
const offsets = offset(el)
console.log(offsets) // Logs: {top: 100, left: 100}

Arguments

+ el: Element

The element you want to get offsets of

Returns

Object Object containing top and left offsets

getElements(target)

Useful to normalize parameters accepted by modules which work with dom nodes. If you need to have an array of Elements and you want to accept any of: String, String array, Element, Element array

import {qs, getElements} from '@okiba/dom'
const els1 = getElements(['.some', '#thing']) // => [div.some, span#it]

const el = qs('.element')
const els2 = getElements(el) // => [el]

Arguments

+ target: String or Array.<String> or Element or Array.<Element>

The target you want to be sure to obtain as an array of Elements

Returns

Array.<Element> An array of Elements

matches(el, selectors, testAncestors)

Checks if an element matches at least one in a list of selectors.

import {matches} from '@okiba/dom'

const isInternal = !!matches(a, '.internal')
//...
const match = matches(myDiv, ['.red', '.green', '.blue])
myDiv.style.backgroundColor = match.replace('.', '')

Arguments

+ el: Element

Element to check

+ selectors: String or Array

Selector (ora array thereof) which the element should match

+ testAncestors: Boolean

If true, extends match test upward in the ancestors

Returns

String First matching selector, null if there was no match

isChildOf(el, target)

Check if a given element is child of another. The target to match can be an element, selector, or array of selectors.

import {isChildOf} from '@okiba/dom'

const isChildOfAnchor = isChildOf(myNode, 'a')
//... or
const isInsideButton = isChildOf(myNode, myButton)

Arguments

+ el: Element

Element to check

+ target: Element or String or Array.<String>

Selector to match or Element checked for parent relationship

Returns

Boolean Boolean of match found

delegate(target, event, callback, options, context)

Delegate an event callback. It will be executed only if the event target has an ancestor which matches the given target

import {delegate} from '@okiba/dom'

const undelegate = delegate('a.internal-navigation', 'click', onNavigationClick, {capture: true})

function disableNavigation() {
  undelegate()
}

Arguments

+ target: String or Element

Selector or Element to match

+ event: String

Event to bind to

+ callback: function

Function to be executed at match

+ options: Object or Boolean

Options to be to on

+ context: Window or HTMLDocument or HTMLElement

Delegation root element

Returns

function Function to be called to remove the delegated callback

createCustomEvent(type, options)

Custom event factory. Creates a cross-browsers compatible custom event instance

import {createCustomEvent} from '@okiba/dom'

const enemy = document.getElementById('enemy')
const shinobiAttack = createCustomEvent('shinobi-attack', {
 detail: { damage: 3 }
})

enemy.setAttribute('data-life-points', 100)

enemy.addEventListener('shinobi-attack', e => {
 const currentLifePoints = enemy.getAttribute('data-life-points')
 const updatedlifePoints = Math.max(0, currentLifePoints - e.detail.damage)
 enemy.setAttribute('data-life-points', updatedlifePoints)
})

enemy.dispatchEvent(shinobiAttack)

console.log(enemy.getAttribute('data-life-points')) // Logs: 97

Arguments

+ type: String

The custom event type

+ options: Object

The custom event options

Returns

CustomEvent The custom event instance