DOM Utils

Basic small typed DOM helpers that aids in the creation of vanilla JS code.

Helps query, create and modify DOM-nodes. Like a mini-jQuery. Somewhat inspired by Bliss.js.

Based on @hdsydsvenskan/dom-utils which was based on my personal utility functions.

Usage

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

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

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

⚠️ Version 2.0.0 Breaking Changes & Deprecations

Many helpers are now deprecated in favor of modern DOM APIs.

Deprecated functions and their modern replacements

| Deprecated Function | Use Instead (Modern DOM API) | |----------------------|-----------------------------------------| | hasClass | element.classList.contains() | | addClass | element.classList.add() | | removeClass | element.classList.remove() | | toggleClass | element.classList.toggle() | | appendChild | element.append() | | emptyElement | element.replaceChildren() | | removeElement | element.remove() | | getDataAttribute | element.dataset | | setDataAttribute | element.dataset | | closestByClass | element.closest() | | is | element.matches() |

These deprecated helpers are still available for backward compatibility, but you are encouraged to migrate to the standard DOM APIs for better performance and future compatibility.

Other changes

• Function signatures now use more precise types (e.g. ParentNode, HTMLElementTagNameMap).
• setAttributes now sets attributes also to falsy non-null/undefined values.

API

Table of Contents

• Querying & Traversing
  • $
  • $$
  • ~~closestByClass~~
  • elemByClass
  • elemsByClass
  • ~~is~~
• Creation & Insertion
  • addText
  • ~~appendChild~~
  • createChild
  • createElement
  • insertBefore
• Attributes & Classes
  • ~~addClass~~
  • ~~getDataAttribute~~
  • ~~hasClass~~
  • ~~removeClass~~
  • setAttributes
  • ~~setDataAttribute~~
  • ~~toggleClass~~
• Manipulation & Removal
  • ~~emptyElement~~
  • ~~removeElement~~
• Types
  • ElementContainer

Querying & Traversing

$()

Like $$(), but returns only a single HTML element. A thin wrapper around querySelector.

If one needs to match against the context container element itself, then use elemByClass() instead.

Syntax

$(selector, [context]) => HTMLElement | undefined

Arguments

• selector – string | Node – A CSS selector string, or a node.
• context – ParentNode – Optional context from which to search. Defaults to document.

Returns

A single HTMLElement or undefined if no match is found.

$$()

Get an array of HTML elements that matches the specified selector. A thin wrapper around querySelectorAll.

Syntax

$$(selector, [context]) => HTMLElement[]

Arguments

• selector – string | Node[] | NodeListOf<Node> – A CSS selector string, or an array/NodeList of nodes.
• context – ParentNode – Optional context from which to search. Defaults to document.

Returns

An array of HTMLElements.

closestByClass()

[!WARNING] Deprecated: Use element.closest() instead.

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

Syntax

closestByClass(elem, className) => HTMLElement | undefined

Arguments

• elem – Node
• className – string

Returns

A single HTMLElement or undefined if no match is found.

elemByClass()

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

Syntax

elemByClass(className, [context]) => HTMLElement | undefined

Arguments

• className – string
• context – ParentNode

elemsByClass()

Like elemByClass() but returns an array of all matching elements within the context.

Syntax

elemsByClass(className, [context]) => HTMLElement[]

Arguments

• className – string
• context – ParentNode

Returns

An array of HTMLElements.

is()

[!WARNING] Deprecated: Use element.matches() instead.

Checks if an element matches a given selector.

Syntax

is(elem, selector) => boolean

Arguments

• elem – Element
• selector – string

Returns

A boolean

Creation & Insertion

addText()

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

Syntax

addText(elem, text) => void

Arguments

• elem – Element
• text – string

appendChild()

[!WARNING] Deprecated: Use element.append() instead.

Helper to append many children nodes at once.

Syntax

appendChild(elem, ...children) => void

Arguments

• elem – ParentNode
• children – ...Node

createChild()

Like createElement(), but also appends the created element to a container.

Syntax

createChild(elem, tag, [classNameOrAttributes], [text]) => HTMLElement

Arguments

• elem – ParentNode
• tag – keyof HTMLElementTagNameMap
• classNameOrAttributes – string | string[] | { [attributeName: string]: string }
• text – string

Returns

The created HTMLElement.

createElement()

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

Syntax

createElement(tag, [classNameOrAttributes], [text]) => HTMLElement

Arguments

• tag – keyof HTMLElementTagNameMap
• classNameOrAttributes – string | string[] | { [attributeName: string]: string }
• text – string

Returns

The created HTMLElement.

insertBefore()

Inserts a child node before a given element.

Syntax

insertBefore(elem, child) => Node

Arguments

• elem – Node – The node to insert before.
• child – Node – The node to insert.

Returns

The inserted child node.

Attributes & Classes

addClass()

[!WARNING] Deprecated: Use element.classList.add() instead.

Syntax

addClass(elem, className) => void

Arguments

• elem – Element
• className – string

getDataAttribute()

[!WARNING] Deprecated: Use element.dataset instead.

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

Syntax

getDataAttribute(elem, attribute) => string | undefined

Arguments

• elem – HTMLElement
• attribute – string – Should be in kebab case.

hasClass()

[!WARNING] Deprecated: Use element.classList.contains() instead.

Syntax

hasClass(elem, className) => boolean

Arguments

• elem – Element
• className – string

removeClass()

[!WARNING] Deprecated: Use element.classList.remove() instead.

Syntax

removeClass(elem, className) => void

Arguments

• elem – Element
• className – string

setAttributes()

Helper to easily set a collection of attributes on an element.

Syntax

setAttributes(elem, attributes) => void

Arguments

• elem – Element
• attributes – { [attributeName: string]: string }

setDataAttribute()

[!WARNING] Deprecated: Use element.dataset instead.

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

Syntax

setDataAttribute(elem, attribute, value) => void

Arguments

• elem – HTMLElement
• attribute – string – Should be in kebab case.
• value – string

toggleClass()

[!WARNING] Deprecated: Use element.classList.toggle() instead.

Syntax

toggleClass(elem, className) => void

Arguments

• elem – Element
• className – string

Manipulation & Removal

emptyElement()

[!WARNING] Deprecated: Use element.replaceChildren() instead.

Iterates over all children in a container and removes them all.

Syntax

emptyElement(elem) => void

Arguments

• elem – ParentNode

removeElement()

[!WARNING] Deprecated: Use element.remove() instead.

Syntax

removeElement(elem) => void

Arguments

• elem – ChildNode

Types

ElementContainer

A type alias for a DOM element that can contain other elements.

export type ElementContainer = Document | DocumentFragment | Element;