@hdsydsvenskan/dom-utils

Basic small typed DOM helpers that aids in the creation of vanilla JS code.
Makes it easy to query, create and modify DOM-nodes – consider it a mini-jQuery. Somewhat inspired by Bliss.js.

Installation

yarn add @hdsydsvenskan/dom-utils

Release new version

Follow Semantic Versioning and use np and a version like patch | minor | major | prepatch | preminor | premajor | prerelease | 1.2.3

np patch

Usage

import {
  $,
  createChild
} from '@hdsydsvenskan/dom-utils';

const elem = $('.a-nice-selector');

createChild(elem, 'div', 'a-nice-selector__bemish-elem', 'With some nice text in it');

Methods and types

Table of Contents

• ElementContainer
• ensureElementContainer
• ensureHTMLElement
• ensureHTMLElements
• $$
• $
• addText
• hasClass
• removeClass
• addClass
• toggleClass
• appendChild
• setAttributes
• removeElement
• emptyElement
• getDataAttribute
• setDataAttribute
• createElement
• createChild
• closestByClass
• elemByClass
• elemsByClass
• insertBefore

ElementContainer

Type: (Document \| DocumentFragment \| Element)

ensureElementContainer

Mostly for internal use. Ensures that the node is of an element container type, mostly helps type validation

Parameters

• elem Node

Returns (ElementContainer \| undefined)

ensureHTMLElement

Mostly for internal use. Ensures that the node is an actual HTML element, mostly helps type validation

Parameters

• elem T

ensureHTMLElements

Mostly for internal use. Ensures that a list of nodes only contains HTML elements, mostly helps type validation

Parameters

• elems Array<T>

$$

Get an array of HTML elements that matches the specified selector

Parameters

• selector T
• context ElementContainer? If set, only looks up elements within the context container

$

Like $$, but returns only a single HTML element
If one needs to match against the context container element itself, then use elemByClass instead

Parameters

• selector T
• context ElementContainer?

addText

Adds text nodes to the supplied element, persisting newlines by adding br elements for each newline

Parameters

• elem Element
• text string

hasClass

Parameters

• elem Element
• className string

Returns boolean

removeClass

Parameters

• elem Element
• className

string
Returns void

addClass

Parameters

• elem Element
• className

string
Returns void

toggleClass

Parameters

• elem Element
• className

string
Returns void

appendChild

Helper to append many children nodes at once

Parameters

• elem ElementContainer
• children

...Node

setAttributes

Helper to easily set a collection of attributes

Parameters

• elem Element
• attributes

removeElement

Parameters

• elem Element

Returns void
Meta

• deprecated: Use element.remove() instead

emptyElement

Iterates over all children in a container and removes them all

Parameters

• elem ElementContainer

getDataAttribute

Helper that makes one don't have to do kebab case conversion oneself

Parameters

• elem HTMLElement
• attribute

string Should be in kebab case
Returns (string \| undefined)

setDataAttribute

Helper that makes one don't have to do kebab case conversion oneself

Parameters

• elem HTMLElement
• attribute

string Should be in kebab case

value

string

createElement

Helper to easily create a new HTML element, with all that one would need for that

Parameters

• tag string
• classNameOrAttributes
text string?

Returns HTMLElement

createChild

Like createElement, but also appends the created element to a container
Helpful when creating multiple elements within one another as one can then send the result of one as the container to the other.

Parameters

• elem ElementContainer
• tag string
• classNameOrAttributes
text string?

Returns HTMLElement

closestByClass

Iterates over the parents of a node and returns the first one that has the specified class name

Parameters

• elem Node
• className

string
Returns (HTMLElement \| undefined)

elemByClass

Like $, but with class name rather than selector + also matches against the context itself, not just elements within it

Parameters

• className string
• context ElementContainer?

Returns (HTMLElement \| undefined)

elemsByClass

Like elemByClass but replaces $$ instead and either returns the context itself if it matches, or a list of matching elements within it

Parameters

• className string
• context ElementContainer?

Returns Array<HTMLElement>

insertBefore

Parameters

• elem Node
• child

T
Returns T