frostdom
v2.1.3
Published
FrostDOM is a free, open-source DOM manipulation library for JavaScript.
Downloads
184
Maintainers
Readme
FrostDOM
FrostDOM is a free, open-source DOM manipulation library for JavaScript.
It is a lightweight (~18kb gzipped) and modern library, utilizing ES6 syntax and features including Promises.
Table Of Contents
Installation
Dependencies
In Browser
<script type="text/javascript" src="/path/to/frost-core.min.js"></script>
<script type="text/javascript" src="/path/to/frost-dom.min.js"></script>
Alternatively, a bundle version is supplied which includes the FrostCore library in a single JS file.
<script type="text/javascript" src="/path/to/frost-dom-bundle.min.js"></script>
Using NPM
npm i frostdom
In Node.js:
const { JSDOM } = require('jsdom');
const { window } = new JSDOM('');
const { dom } = require('frostdom')(window);
DOM
The DOM class provides all the base methods for manipulating the DOM, performing AJAX requests, handling cookies and more.
By default, a DOM class is created on the document
context, and is assigned to the lowercase dom
variable in the global scope.
However, it is possible to create additional instances of the class on any Document context.
const myDOM = new DOM(context);
Animate
Animate
Add an animation to each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.callback
is a function that acceptsnode
,progress
andoptions
as arguments, wherenode
is a HTMLElement,progress
is a value between 0 and 1 andoptions
is theoptions
object passed to this method.options
is an object containing properties to define how the animation should be handled.duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either ease-in, ease-out, ease-in-out or linear indicating the type of animation to run, and will default to ease-in-out.infinite
is a boolean indicating whether the animation should continue forever, and will default to false.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.animate(nodes, callback, options);
Stop Animations
Stop all animations for each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.finish
is a boolean indicating whether to immediately finish the animation, and will default to true.
dom.stop(nodes, finish);
Animations
Drop In
Drop each node into place.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of node.options
is an object containing properties to define how the animation should be handled.direction
is a string or function that returns either "top", "right", "bottom" or "left" indicating the direction to drop from, and will default to "top".duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either "ease-in", "ease-out", "ease-in-out" or "linear" indicating the type of animation to run, and will default to "ease-in-out".infinite
is a boolean indicating whether the animation should continue forever, and will default to false.useGpu
is a boolean indicating whether the animation should use GPU acceleration (CSS transform) and will default to true.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.dropIn(nodes, options);
Drop Out
Drop each node out of place.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.options
is an object containing properties to define how the animation should be handled.direction
is a string or function that returns either "top", "right", "bottom" or "left" indicating the direction to drop from, and will default to "top".duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either "ease-in", "ease-out", "ease-in-out" or "linear" indicating the type of animation to run, and will default to "ease-in-out".infinite
is a boolean indicating whether the animation should continue forever, and will default to false.useGpu
is a boolean indicating whether the animation should use GPU acceleration (CSS transform) and will default to true.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.dropOut(nodes, options);
Fade In
Fade the opacity of each node in.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.options
is an object containing properties to define how the animation should be handled.duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either "ease-in", "ease-out", "ease-in-out" or "linear" indicating the type of animation to run, and will default to "ease-in-out".infinite
is a boolean indicating whether the animation should continue forever, and will default to false.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.fadeIn(nodes, options);
Fade Out
Fade the opacity of each node out.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.options
is an object containing properties to define how the animation should be handled.duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either "ease-in", "ease-out", "ease-in-out" or "linear" indicating the type of animation to run, and will default to "ease-in-out".infinite
is a boolean indicating whether the animation should continue forever, and will default to false.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.fadeOut(nodes, options);
Rotate In
Rotate each node in on an X, Y or Z.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.options
is an object containing properties to define how the animation should be handled.x
is the amount of rotation to apply to the X axis, and will default to 0.y
is the amount of rotation to apply to the Y axis, and will default to 1.z
is the amount of rotation to apply to the Z axis, and will default to 0.inverse
is a boolean indicating whether to rotate in the opposite direction, and will default to false.duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either "ease-in", "ease-out", "ease-in-out" or "linear" indicating the type of animation to run, and will default to "ease-in-out".infinite
is a boolean indicating whether the animation should continue forever, and will default to false.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.rotateIn(nodes, options);
Rotate Out
Rotate each node out on an X, Y or Z.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.options
is an object containing properties to define how the animation should be handled.x
is the amount of rotation to apply to the X axis, and will default to 0.y
is the amount of rotation to apply to the Y axis, and will default to 1.z
is the amount of rotation to apply to the Z axis, and will default to 0.inverse
is a boolean indicating whether to rotate in the opposite direction, and will default to false.duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either "ease-in", "ease-out", "ease-in-out" or "linear" indicating the type of animation to run, and will default to "ease-in-out".infinite
is a boolean indicating whether the animation should continue forever, and will default to false.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.rotateOut(nodes, options);
Slide In
Slide each node into place to a direction.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.options
is an object containing properties to define how the animation should be handled.direction
is a string or function that returns either "top", "right", "bottom" or "left" indicating the direction to slide from, and will default to "top".duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either "ease-in", "ease-out", "ease-in-out" or "linear" indicating the type of animation to run, and will default to "ease-in-out".infinite
is a boolean indicating whether the animation should continue forever, and will default to false.useGpu
is a boolean indicating whether the animation should use GPU acceleration (CSS transform) and will default to true.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.slideIn(nodes, options);
Slide Out
Slide each node out of place from a direction.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.options
is an object containing properties to define how the animation should be handled.direction
is a string or function that returns either "top", "right", "bottom" or "left" indicating the direction to slide from, and will default to "top".duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either "ease-in", "ease-out", "ease-in-out" or "linear" indicating the type of animation to run, and will default to "ease-in-out".infinite
is a boolean indicating whether the animation should continue forever, and will default to false.useGpu
is a boolean indicating whether the animation should use GPU acceleration (CSS transform) and will default to true.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.slideOut(nodes, options);
Squeeze In
Squeeze each node into place to a direction.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.options
is an object containing properties to define how the animation should be handled.direction
is a string or function that returns either "top", "right", "bottom" or "left" indicating the direction to squeeze from, and will default to "top".duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either "ease-in", "ease-out", "ease-in-out" or "linear" indicating the type of animation to run, and will default to "ease-in-out".infinite
is a boolean indicating whether the animation should continue forever, and will default to false.useGpu
is a boolean indicating whether the animation should use GPU acceleration (CSS transform) and will default to true.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.squeezeIn(nodes, options);
Squeeze Out
Squeeze each node out of place from a direction.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.options
is an object containing properties to define how the animation should be handled.direction
is a string or function that returns either "top", "right", "bottom" or "left" indicating the direction to squeeze from, and will default to "top".duration
is the number of milliseconds that the animation should last, and will default to 1000.type
is a string of either "ease-in", "ease-out", "ease-in-out" or "linear" indicating the type of animation to run, and will default to "ease-in-out".infinite
is a boolean indicating whether the animation should continue forever, and will default to false.useGpu
is a boolean indicating whether the animation should use GPU acceleration (CSS transform) and will default to true.
This method returns an AnimationSet that will resolve after the animation has completed.
const animation = dom.squeezeOut(nodes, options);
Queue
Clear Queue
Clear a queue of each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.queueName
is a string indicating the name of the queue to clear, and will default to "default".
dom.clearQueue(nodes, queueName);
If the queueName
is set to false, then all queues will be cleared.
Queue
Queue a callback on each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.callback
is a function that acceptsnode
as an argument, where node is a HTMLElement. The callback can return a Promise which will pause the queue until the promise is resolved.queueName
is a string indicating the name of the queue to use, and will default to "default".
dom.queue(nodes, callback);
If an item in the queue returns a Promise that rejects, the queue will be cleared.
Attributes
Get Attribute
Get an attribute value for the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.attribute
is a string indicating the attribute value to return.
const value = dom.getAttribute(nodes, attribute);
If the attribute
argument is omitted, an object containing all attribute values will be returned instead.
const attributes = dom.getAttribute(nodes);
Get Dataset
Get a dataset value for the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.key
is a string indicating the dataset value to return.
const value = dom.getDataset(nodes, key);
If the key
argument is omitted, an object containing all dataset values will be returned instead.
const dataset = dom.getDataset(nodes);
This method will attempt to convert string values to JS primitives (including booleans, numbers, objects, arrays and null).
Get HTML
Get the HTML contents of the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
const html = dom.getHTML(nodes);
Get Property
Get a property value for the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.property
is a string indicating the property value to return.
const value = dom.getProperty(nodes, property);
Get Text
Get the text contents of the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
const text = dom.getText(nodes);
Get Value
Get the value property of the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
const value = dom.getValue(nodes);
Remove Attribute
Remove an attribute from each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.attribute
is a string indicating the attribute value to remove.
dom.removeAttribute(nodes, attribute);
Remove Dataset
Remove a dataset value from each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.key
is a string indicating the dataset value to remove.
dom.removeDataset(nodes, key);
Remove Property
Remove a property from each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.property
is a string indicating the property value to remove.
dom.removeProperty(nodes, property);
Set Attribute
Set attributes for each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.attribute
is a string indicating the attribute value to set.value
is the value you want to set the attribute to.
dom.setAttribute(nodes, attribute, value);
Alternatively, you can set multiple attributes by passing a single attributes
object as the argument with key/value pairs of the attributes to set.
dom.setAttribute(nodes, attributes);
Set Dataset
Set dataset values for each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.key
is a string indicating the dataset value to set.value
is the value you want to set the dataset to.
dom.setDataset(nodes, key, value);
Alternatively, you can set multiple dataset properties by passing a single dataset
object as the argument with key/value pairs of the properties to set.
dom.setDataset(nodes, dataset);
This method will convert object and array values to JSON strings.
Set HTML
Set the HTML contents for each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of node.html
is a string that will become the HTML contents of the node.
dom.setHTML(nodes, html);
Set Property
Set property values for each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.property
is a string indicating the property value to set.value
is the value you want to set the property to.
dom.setProperty(nodes, property, value);
Alternatively, you can set multiple properties by passing a single properties
object as the argument with key/value pairs of the properties to set.
dom.setProperty(nodes, properties);
Set Text
Set the text contents for each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.text
is a string that will become the text contents of the node.
dom.setText(nodes, text);
Set Value
Set the value property for each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.value
is a string that will become the value of the node.
dom.setValue(nodes, value);
Custom Data
Clone Data
Clone custom data from each node to each other node.
nodes
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.cloneData(nodes, others);
Get Data
Get custom data for the first node.
nodes
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.key
is a string indicating the custom data value to return.
const value = dom.getData(nodes, key);
If the key
argument is omitted, an object containing all custom data values will be returned instead.
const data = dom.getData(nodes);
Remove Data
Remove custom data for each node.
nodes
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.key
is a string indicating the custom data value to remove.
dom.removeData(nodes, key);
Set Data
Set custom data for each node.
nodes
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.key
is a string indicating the custom data value to set.value
is the value you want to set the attribute to.
dom.setData(nodes, key, value);
Alternatively, you can set multiple data values by passing a single data
object as the argument with key/value pairs of the data to set.
dom.setData(nodes, data);
Position
Center
Get the X,Y co-ordinates for the center of the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.offset
is a boolean indicating whether the co-ordinates should be offset from the top left of the document, and will default to false.
const center = dom.center(nodes, offset);
Constrain
Constrain each node to a container node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.container
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.constrain(nodes, container);
Distance To
Get the distance of the first node to an X,Y position.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.x
is a distance (in pixels) along the X axis.y
is a distance (in pixels) along the Y axis.offset
is a boolean indicating whether the co-ordinates should be offset from the top left of the document, and will default to false.
const dist = dom.distTo(nodes, x, y, offset);
Distance To Node
Get the distance between two nodes.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
const dist = dom.distToNode(nodes, others);
Nearest To
Get the nearest node to an X,Y position.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.x
is a distance (in pixels) along the X axis.y
is a distance (in pixels) along the Y axis.offset
is a boolean indicating whether the co-ordinates should be offset from the top left of the document, and will default to false.
const nearest = dom.nearestTo(nodes, x, y, offset);
Nearest To Node
Get the nearest node to another node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
const nearest = dom.nearestToNode(nodes, others);
Percent X
Get the percentage of an X co-ordinate relative to the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.x
is a distance (in pixels) along the X axis.offset
is a boolean indicating whether the co-ordinates should be offset from the top left of the document, and will default to false.clamp
is a boolean indicating whether to clamp the percent betwen 0 and 100, and will default to true.
const percentX = dom.percentX(nodes, x, offset, clamp);
Percent Y
Get the percentage of a Y co-ordinate relative to the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.y
is a distance (in pixels) along the Y axis.offset
is a boolean indicating whether the co-ordinates should be offset from the top left of the document, and will default to false.clamp
is a boolean indicating whether to clamp the percent betwen 0 and 100, and will default to true.
const percentY = dom.percentY(nodes, y, offset, clamp);
Position
Get the X,Y position for the top/left of the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.offset
is a boolean indicating whether the co-ordinates should be offset from the top left of the document, and will default to false.
const position = dom.position(nodes, offset);
Rectangle
Get the computed bounding rectangle of the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.offset
is a boolean indicating whether the rectangle should be offset from the top left of the document, and will default to false.
const rect = dom.rect(nodes, offset);
Scroll
Get Scroll X
Get the scroll X position of the first node.
nodes
is a query selector string, a HTMLElement, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.
const scrollX = dom.getScrollX(nodes);
Get Scroll Y
Get the scroll Y position of the first node.
nodes
is a query selector string, a HTMLElement, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.
const scrollY = dom.getScrollY(nodes);
Set Scroll
Scroll each node to an X,Y position.
nodes
is a query selector string, a HTMLElement, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.x
is a distance (in pixels) along the X axis to scroll to.y
is a distance (in pixels) along the Y axis to scroll to.
dom.setScroll(nodes, x, y);
Set Scroll X
Scroll each node to an X position.
nodes
is a query selector string, a HTMLElement, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.x
is a distance (in pixels) along the X axis to scroll to.
dom.setScrollX(nodes, x);
Set Scroll Y
Scroll each node to a Y position.
nodes
is a query selector string, a HTMLElement, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.y
is a distance (in pixels) along the Y axis to scroll to.
dom.setScrollY(nodes, y);
Size
Height
Get the computed height of the first node.
nodes
is a query selector string, a HTMLElement, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.boxSize
is a number indicating the box sizing to calculate. Allowed values are 0 (no padding), 1 (padding), 2 (padding and border), 3 (padding, border and margin) and 4 (scroll area), and will default to 1.
const height = dom.height(nodes, boxSize);
If the first node passed to this method is a Window, the second argument will instead determine whether to use the outer height, and will default to false.
The following constants can also be used as the second argument for brevity.
DOM.CONTENT_BOX
0DOM.PADDING_BOX
1DOM.BORDER_BOX
2DOM.MARGIN_BOX
3DOM.SCROLL_BOX
4
Width
Get the computed width of the first node.
nodes
is a query selector string, a HTMLElement, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.boxSize
is a number indicating the box sizing to calculate. Allowed values are 0 (no padding), 1 (padding), 2 (padding and border), 3 (padding, border and margin) and 4 (scroll area), and will default to 1.
const width = dom.width(nodes, boxSize);
If the first node passed to this method is a Window, the second argument will instead determine whether to use the outer width, and will default to false.
The following constants can also be used as the second argument for brevity.
DOM.CONTENT_BOX
0DOM.PADDING_BOX
1DOM.BORDER_BOX
2DOM.MARGIN_BOX
3DOM.SCROLL_BOX
4
Styles
Add Class
Add a class or classes to each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.classes
is an array of classes, or a space seperated string of class names.
dom.addClass(nodes, ...classes);
Computed Style
Get a computed CSS style value for the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.style
is a string indicating the computed style property value to return.
const value = dom.css(nodes, style);
If the style
argument is omitted, an object containing all computed style values will be returned instead.
const css = dom.css(nodes);
Get Style
Get a style property for the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.style
is a string indicating the style property value to return.
const value = dom.getStyle(nodes, style);
If the style
argument is omitted, an object containing all style values will be returned instead.
const styles = dom.getStyle(nodes);
Hide
Hide each node from display.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.hide(nodes);
Remove Class
Remove a class or classes from each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.classes
is an array of classes, or a space seperated string of class names.
dom.removeClass(nodes, ...classes);
Set Style
Set style properties for each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.style
is a string indicating the style property value to set.value
is the value you wish to set the style property to.important
is a boolean indicating the style should be set as important, and will default to false.
dom.setStyle(nodes, style, value, important);
Alternatively, you can set multiple style properties by passing a single styles
object as the argument with key/value pairs of the styles to set.
dom.setStyle(nodes, styles);
Show
Display each hidden node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.show(nodes);
Toggle
Toggle the visibility of each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.toggle(nodes);
Toggle Class
Toggle a class or classes for each node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.classes
is an array of classes, or a space seperated string of class names.
dom.toggleClass(nodes, ...classes);
Events
Blur
Trigger a blur event on the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.blur(nodes);
Click
Trigger a click event on the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.click(nodes);
Focus
Trigger a focus event on the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.focus(nodes);
Ready
Add a function to the ready queue.
callback
is a function that will execute once the DOM has finished loading.
If the DOM is already loaded, callback
will execute immediately.
dom.ready(callback);
Event Handlers
Add Event
Add events to each node.
nodes
is a query selector string, a HTMLElement, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.events
is a space-separated string of events to attach to the nodes.callback
is a function that accepts anevent
argument, which will be called when the event is triggered.useCapture
is a boolean indicating whether to use a capture event, and will default to false.
dom.addEvent(nodes, events, callback, useCapture);
Add Event Delegate
Add delegated events to each node.
nodes
is a query selector string, a HTMLElement, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.events
is a space-separated string of events to attach to the nodes.delegate
is a query selector string which will only trigger the event if it is propagated by a target matching the selector.callback
is a function that accepts anevent
argument, which will be called when the event is triggered.useCapture
is a boolean indicating whether to use a capture event, and will default to false.
dom.addEventDelegate(nodes, events, delegate, callback, useCapture);
Add Event Delegate Once
Add self-destructing delegated events to each node.
nodes
is a query selector string, a HTMLElement, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.events
is a space-separated string of events to attach to the nodes.delegate
is a query selector string which will only trigger the event if it is propagated by a target matching the selector.callback
is a function that accepts anevent
argument, which will be called when the event is triggered.useCapture
is a boolean indicating whether to use a capture event, and will default to false.
dom.addEventDelegateOnce(nodes, events, delegate, callback, useCapture);
Add Event Once
Add self-destructing events to each node.
nodes
is a query selector string, a HTMLElement, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.events
is a space-separated string of events to attach to the nodes.callback
is a function that accepts anevent
argument, which will be called when the event is triggered.useCapture
is a boolean indicating whether to use a capture event, and will default to false.
dom.addEventOnce(nodes, events, callback, useCapture);
Clone Events
Clone all events from each node to other nodes.
nodes
is a query selector string, a HTMLElement, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTMLElement, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.cloneEvents(nodes, others);
Remove Event
Remove events from each node.
nodes
is a query selector string, a HTMLElement, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.events
is a space-separated string of events to remove from the nodes.callback
is a function that accepts anevent
argument, which will be called when the event is triggered.useCapture
is a boolean indicating whether to use a capture event, and will default to null.
dom.removeEvent(nodes, events, callback, useCapture);
If the events
, callback
or useCapture
arguments are omitted, this method will remove all matching events from each node.
Remove Event Delegate
Remove delegated events from each node.
nodes
is a query selector string, a HTMLElement, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.events
is a space-separated string of events to remove from the nodes.delegate
is a query selector string which will only trigger the event if it is propagated by a target matching the selector.callback
is a function that accepts anevent
argument, which will be called when the event is triggered.useCapture
is a boolean indicating whether to use a capture event, and will default to null.
dom.removeEventDelegate(nodes, events, delegate, callback, useCapture);
Trigger Event
Trigger events on each node.
nodes
is a query selector string, a HTMLElement, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.events
is a space-separated string of events to trigger on the nodes.options
is an object containing properties to define the new Event.detail
can be used to attach additional data to the event.bubbles
is a boolean indicating whether the event should bubble, and will default to true.cancelable
is a boolean indicating whether the event is cancelable, and will default to true.
dom.triggerEvent(nodes, events, options);
Trigger One
Trigger an event on the first node.
nodes
is a query selector string, a HTMLElement, ShadowRoot, Document, Window, NodeList, HTMLCollection, QuerySet or an array of nodes.event
is an event to trigger on the nodes.options
is an object containing properties to define the new Event.detail
can be used to attach additional data to the event.bubbles
is a boolean indicating whether the event should bubble, and will default to true.cancelable
is a boolean indicating whether the event is cancelable, and will default to true.
const cancelled = !dom.triggerOne(nodes, event, options);
This method returns false if the event was cancelled, otherwise returns true.
Event Factory
Mouse Drag Event Factory
Create a mouse drag event (optionally limited by animation frame).
down
is a function that accepts an event argument, which will be called when the event is started.move
is a function that accepts an event argument, which will be called when the mouse is moved during the event.up
is a function that accepts an event argument, which will be called when the event has ended (mouse button has been released).options
is an object containing configuration options for the drag event.debounce
is a boolean indicating whether to debounce the move event, and will default to true.passive
is a boolean indicating whether to use passive event listeners, and will default to true.
const drag = dom.mouseDragFactory(down, move, up, debounce);
This method also works with touch events.
Manipulation
Clone
Clone each node (optionally deep, and with events and data).
nodes
is a query selector string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.options
is an object containing properties to define the new node.deep
is a boolean indicating whether to also clone child nodes, and will default to true.events
is a boolean indicating whether to also clone events, and will default to false.data
is a boolean indicating whether to also clone data, and will default to false.animations
is a boolean indicating whether to also clone animations, and will default to false.
const clones = dom.clone(nodes, options);
Detach
Detach each node from the DOM.
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
const detached = dom.detach(nodes);
Empty
Remove all children of each node from the DOM.
nodes
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.empty(nodes);
Remove
Remove each node from the DOM.
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.remove(nodes);
Replace All
Replace each other node with nodes.
nodes
is a query selector string, a HTML string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a Node, HTMLElement NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.replaceAll(nodes, others);
If a node you are replacing with is a DocumentFragment, the fragment contents will be used as a replacement.
If multiple nodes are being replaced, cloned nodes will be created for each except for the last one.
All events, data and animations will be removed from each node that is replaced.
Replace With
Replace each node with other nodes.
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTML string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.replaceWith(nodes, others);
If a node you are replacing with is a DocumentFragment, the fragment contents will be used as a replacement.
If multiple nodes are being replaced, cloned nodes will be created for each except for the last one.
All events, data and animations will be removed from each node that is replaced.
Create
Attach Shadow
Attach a shadow DOM tree to the first node.
nodes
is a query selector string, aHTMLElement, HTMLCollection, QuerySet or an array of nodes.open
is a boolean indicating whether the nodes are accessible from JavaScript outside the root, and will default to true.
const shadow = dom.attachShadow(nodes, open);
Create
Create a new DOM element.
tagName
is a string indicating the type of element you wish to create, and will default to "div".options
is an object containing properties to define the new node.html
is a string that will become the HTML contents of the node.text
is a string that will become the text contents of the node.class
is an array of classes, or a space seperated string of class names.style
is an object containing style values to set.value
is a string that will become the value of the node.attributes
is an object containing attribute values to set.properties
is an object containing property values to set.dataset
is an object containing dataset values to set.
const element = dom.create(tagName, options);
Create Comment
Create a new comment node.
comment
is a string indicating the comment.
const commentNode = dom.createComment(comment);
Create Fragment
Create a new document fragment.
const fragment = dom.createFragment();
Create Range
Create a new range object.
const range = dom.createRange();
Create Text
Create a new text node.
text
is a string indicating the text.
const textNode = dom.createText(text);
Parse HTML
Return an array containing nodes parsed from a HTML string.
html
is a string containing the HTML data to parse.
const nodes = dom.parseHTML(html);
Move
After
Insert each other node after each node.
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTML string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.after(nodes, others);
If a node you are moving is a DocumentFragment, the contents will be moved instead.
If multiple copies of the nodes are being moved, cloned nodes will be created for each except for the last one.
Append
Append each other node to each node.
nodes
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTML string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.append(nodes, others);
If a node you are moving is a DocumentFragment, the contents will be moved instead.
If multiple copies of the nodes are being moved, cloned nodes will be created for each except for the last one.
Append To
Append each node to each other node.
nodes
is a query selector string, a HTML string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.appendTo(nodes, others);
If a node you are moving is a DocumentFragment, the contents will be moved instead.
If multiple copies of the nodes are being moved, cloned nodes will be created for each except for the last one.
Before
Insert each other node before each node.
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTML string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.before(nodes, others);
If a node you are moving is a DocumentFragment, the contents will be moved instead.
If multiple copies of the nodes are being moved, cloned nodes will be created for each except for the last one.
Insert After
Insert each node after each other node.
nodes
is a query selector string, a HTML string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.insertAfter(nodes, others);
If a node you are moving is a DocumentFragment, the contents will be moved instead.
If multiple copies of the nodes are being moved, cloned nodes will be created for each except for the last one.
Insert Before
Insert each node before each other node.
nodes
is a query selector string, a HTML string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.insertBefore(nodes, others);
If a node you are moving is a DocumentFragment, the contents will be moved instead.
If multiple copies of the nodes are being moved, cloned nodes will be created for each except for the last one.
Prepend
Prepend each other node to each node.
nodes
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTML string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.prepend(nodes, others);
If a node you are moving is a DocumentFragment, the contents will be moved instead.
If multiple copies of the nodes are being moved, cloned nodes will be created for each except for the last one.
Prepend To
Prepend each node to each other node.
nodes
is a query selector string, a HTML string, a Node, HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.prependTo(nodes, others);
If a node you are moving is a DocumentFragment, the contents will be moved instead.
If multiple copies of the nodes are being moved, cloned nodes will be created for each except for the last one.
Wrap
Unwrap
Unwrap each node.
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that must match the parent of each node for it to be unwrapped.
dom.unwrap(nodes, filter);
Wrap
Wrap each node with other nodes.
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTML string, a HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.wrap(nodes, others);
If a node you are wrapping with is a DocumentFragment, the contents will be used to wrap instead.
Wrap All
Wrap all nodes with other nodes.
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTML string, a HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.wrapAll(nodes, others);
Wrap Inner
Wrap the contents of each node with other nodes.
nodes
is a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes.others
is a query selector string, a HTML string, a HTMLElement, DocumentFragment, NodeList, HTMLCollection, QuerySet or an array of nodes.
dom.wrapInner(nodes, others);
If a node you are wrapping with is a DocumentFragment, the contents will be used to wrap instead.
Traversal
Child
Find the first child of each node (optionally matching a filter).
nodes
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that the nodes will be filtered by, and will default to false.
const child = dom.child(nodes, filter);
Children
Find all children of each node (optionally matching a filter).
nodes
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that the nodes will be filtered by, and will default to false.
const children = dom.children(nodes, filter);
Closest
Find the closest ancestor to each node (optionally matching a filter, and before a limit).
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that the nodes will be filtered by, and will default to false.limit
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that when matched will stop the search, and will default to false.
const closest = dom.closest(nodes, filter, limit);
Common Ancestor
Find the common ancestor of all nodes.
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
const commonAncestor = dom.commonAncestor(nodes);
Contents
Find all children of each node (including text and comment nodes).
nodes
is a query selector string, a HTMLElement, DocumentFragment, ShadowRoot, Document, NodeList, HTMLCollection, QuerySet or an array of nodes.
const contents = dom.contents(nodes);
Fragment
Return the DocumentFragment of the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
const fragment = dom.fragment(nodes);
Next
Find the next sibling for each node (optionally matching a filter).
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that the nodes will be filtered by, and will default to false.
const next = dom.next(nodes, filter);
Next All
Find all next siblings for each node (optionally matching a filter, and before a limit).
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that the nodes will be filtered by, and will default to false.limit
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that when matched will stop the search, and will default to false.first
is a boolean indicating whether to only return the first matching node for each node, and will default to false.
const nextAll = dom.nextAll(nodes, filter, limit, first);
Offset Parent
Find the offset parent (relatively positioned) of the first node.
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
const offsetParent = dom.offsetParent(nodes);
Parent
Find the parent of each node (optionally matching a filter).
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that the nodes will be filtered by, and will default to false.
const parent = dom.parent(nodes, filter);
Parents
Find all parents of each node (optionally matching a filter, and before a limit).
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that the nodes will be filtered by, and will default to false.limit
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that when matched will stop the search, and will default to false.first
is a boolean indicating whether to only return the first matching node for each node, and will default to false.
const parents = dom.parents(nodes, filter, limit, first);
Previous
Find the previous sibling for each node (optionally matching a filter).
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that the nodes will be filtered by, and will default to false.
const prev = dom.prev(nodes, filter);
Previous All
Find all previous siblings for each node (optionally matching a filter, and before a limit).
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that the nodes will be filtered by, and will default to false.limit
is either a function that accepts anode
argument, a query selector string, a Node, HTMLElement, DocumentFragment, ShadowRoot, NodeList, HTMLCollection, QuerySet or an array of nodes that when matched will stop the search, and will default to false.first
is a boolean indicating whether to only return the first matching node for each node, and will default to false.
const prevAll = dom.prevAll(nodes, filter, limit, first);
Shadow
Return the ShadowRoot of the first node.
nodes
is a query selector string, a HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.
const shadow = dom.shadow(nodes);
Siblings
Find all siblings for each node (optionally matching a filter).
nodes
is a query selector string, a Node, HTMLElement, NodeList, HTMLCollection, QuerySet or an array of nodes.filter
is either a function that accepts anode
argument, a query selector string, a Node,