# DOM

Easily interface with the DOM for updates and retrieval

Wee makes modifying and extracting data from your markup easy with a robust set of DOM functions. We’ve only included what you need without the cruft. You can also chain your methods.

# $ Selection

Get matches to specified selector or return parsed HTML

# Simple

import $ from 'wee-dom';

$('.js-element li');

[node, node, ...]

# Contextual

The context selection subsets the query to a more specific scope. This can result in a more limited and efficient traversal of the DOM.

import $ from 'wee-dom';

$('li', '.js-element');

[node, node, ...]

# Selection of DOM elements

Wee accepts any browser-supported selection queries. Internally Wee parses the selection string to invoke the most efficient native selection method and returns an array of matching nodes.

# Examples

$('#id');
$('.class');
$('#id .class');
$('.class1, .class2');
$('.parent > .child');

# data-ref

References are a logical approach to selecting elements. They are cached when the page loads making them extremely quick to reference and are more visually distinct in markup than js- classes. Anywhere you can pass a standard selector you can also pass a ‘ref:name’ string.

<div data-ref="element"></div>

$('ref:element');

// Shorthand
$(':element');

References can’t be used in subset selectors like $('ref:element .child'). To scope a selection within a reference pass the ref selector as the context argument like $('.child', 'ref:element').

If multiple references are set with the same name they are pushed into an array and can be targeted with a single ref selection. You can also provide a comma-delimited list of multiple refs.

<div data-ref="element"></div>
<div data-ref="element element2"></div>

$('ref:element');

$('ref:element, ref:element2');

# $el.addClass

Add classes to each matching selection

# Single

import $ from 'wee-dom';

$('ref:element').addClass('modifier');

# Multiple

Separate multiple class names with spaces.

import $ from 'wee-dom';

$('ref:element').addClass('modifier modifier2');

# Function

The current index and class value are injected into the callback. The scope of this is the element.

import $ from 'wee-dom';

$('ref:element').addClass(function(i, className) {
    // Add an indexed class

    return className + i;
});

Note: The index argument is always 0-based.

# $el.after

Insert selection or markup after each matching selection

# Selection

import $ from 'wee-dom';

$('ref:element').after($('.js-element'));

# Markup

import $ from 'wee-dom';

$('ref:element').after('<span>Injected notice</span>');

# Function

The current index and HTML are injected into the callback. The scope of this is the element.

<div data-name="John Smith">
    <h1 data-ref="bioName">Name</h1>
</div>

import $ from 'wee-dom';

$(':bioName').after(function(i, html) {
    // Add the parent data-name as a paragraph after the matched element
    return `<p>${$(this).parent().data('name')}</p>`;
});

<div data-name="John Smith">
    <h1 data-ref="bioName">Name</h1>
    <p>John Smith</p>
</div>

# $el.append

Append selection or markup after each matching selection

# Selection

import $ from 'wee-dom';

$('ref:element').append($('.js-element'));

# Function

The current index and HTML are injected into the callback. The scope of this is the element.

<h1 data-ref="listHeading">Names</h1>
<ul>
    <li>John Doe</li>
    <li>Jane Doe</li>
</ul>

import $ from 'wee-dom';
import $children from 'core/types';

$('ref:listHeading').append(function(i, html){
    // Modify the heading to include the number of listed names
    return `(${$(this).children($(this)next()).length})`;
});

<h1 data-ref="listHeading">Names (2)</h1>
<ul>
    <li>John Doe</li>
    <li>Jane Doe</li>
</ul>

# $el.attr

Get attribute of first matching selection or set attribute of each matching selection

# Get

import $ from 'wee-dom';

$('ref:element').attr('href');

"https://www.weepower.com"

# Single

import $ from 'wee-dom';

$('ref:element').attr('href', 'https://www.weepower.com/start');

# Multiple

import $ from 'wee-dom';

$('ref:element').attr({
    href: 'https://developer.mozilla.org',
    target: '_blank'
});

# $el.before

Insert selection or markup before each matching selection

# Selection

import $ from 'wee-dom';

$('ref:element').before($('.js-element'));

# Markup

import $ from 'wee-dom';

$('ref:element').before('<span>Injected notice</span>');

# Function

import $ from 'wee-dom';

$('ref:element').before(function(i, html) {
    //Callback logic
});

# $el.children

Get unique direct children of each matching selection

# All Children

Without a filter all direct children will be returned.

import $ from 'wee-dom';

$('ref:element').children();

# Filtered

With a filter, only matching children will be returned.

import $ from 'wee-dom';

$('ref:element').children('li');

The response excludes text and comment nodes.

# $el.clone

Clone each matching selection

import $ from 'wee-dom';

$('ref.element').clone();

# $el.closest

Get unique closest ancestors of each matching selection

<div class="js-nav">
    <a class="js-link-account">Your Account</a>
</div>
<div class="nav">
    <a class="js-link-about">About Us</a>
</div>

import $ from 'wee-dom';

$('.js-link-about').closest('.js-nav');

<div class="js-nav">
<a class="js-link-about">About Us</a>
</div>

This method traverses up the DOM for the closest match. It doesn't match descendants.

# $el.contains

Determine if any matching parent selection contains descendant selection

import $ from 'wee-dom';

$('ref:element').contains('.descendant');

true

# $el.contents

Get unique content of each matching selection

import $ from 'wee-dom';

$('ref:element').contents();

The response includes text and comment nodes.

# $el.css

Get CSS value of first matching selection or set value of each matching selection

# Get Value

import $ from 'wee-dom';

$('ref:element').css('marginTop');

"0px"

# Set Single Value

import $ from 'wee-dom';

$('ref:element').css('marginTop', '5px');

# Set Multiple Values

import $ from 'wee-dom';

$('ref:element').css({
    marginTop: '5px',
    color: 'red'
});

# $el.data

Get data of first matching selection or set data of each matching selection

# Get All

<div data-ref="element" data-id="150"></div>

import $ from 'wee-dom';

$('ref:element').data();

{
    ref: "element",
    id: 150
}

# Get Single

<div data-ref="element" data-id="150"></div>

import $ from 'wee-dom';

$('ref:element').data('id');

150

# Set Single

import $ from 'wee-dom';

$('ref:element').data('id', '250');

# Set Multiple

import $ from 'wee-dom';

$('ref:element').data({
    id: '350',
    active: 'true'
});

# $el.each

Execute function for each element in selection

import $ from 'wee-dom';

$('.js-element').each((el, i) => {
    // Callback logic
});

# $el.empty

Remove child nodes from each matching selection

<div data-ref="bio">
    <h1>John Smith</h1>
    <p>Lorem ipsum dolor.</p>
</div>

import $ from 'wee-dom';

$('ref:bio').empty();

<div data-ref="bio"></div>

# $el.eq

Get indexed node of matching selection

<ul class="js-element">
    <li>List item 1</li>
    <li>List item 2</li>
    <li>List item 3</li>
|</ul>

import $ from 'wee-dom';

$('.js-element li').eq(1));

<li>List item 2</li>

# Negative Index

import $ from 'wee-dom';

$('.js-element li').eq(-1));

<li>List item 3</li>

# $el.filter

Return a filtered subset of elements from a matching selection

# Selection

import $ from 'wee-dom';

$('ref:element').filter('.filter');

# Function

The current index and element are injected into the callback. The scope of this is the element.

<ul class="people">
    <li>John Doe</li>
    <li>John Smith</li>
    <li>Jane Doe</li>
    <li>Jane Smith</li>
</ul>

import $ from 'wee-dom';

$('.people li').filter((i, el) => {
    //Return elements containing 'Doe'return $text(el).indexOf('Doe') !== -1;
});

[<li>John Doe</li>, <li>Jane Doe</li>]

# $el.find

Get unique filtered descendants from each matching selection

import $ from 'wee-dom';

$('table').find('tr');

# $el.first

Get the first element of a matching selection

import $ from 'wee-dom';

const $first = $('ref:element').first();

# $el.hasClass

Determine if the matching selection has a class

# Single

<div class="hello" data-ref="element"></div>

import $ from 'wee-dom';

$('ref:element').hasClass('hello');
$('ref:element').hasClass('donuts');

true
false

# $el.height

Get or set the height of each matching selection

# Get

import $ from 'wee-dom';

$('ref:element').height();

100

# Outer Height

import $ from 'wee-dom';

$('ref:element').height(true);

120

The value returned is a unitless pixel value.

# Set

import $ from 'wee-dom';

$('ref:element').height('10rem');

# Function

The current index and height are injected into the callback. The scope of this is the element.

<div data-ref="example" style="height: 100px;"></div>

import $ from 'wee-dom';

$('ref:example').height((i, height) => {
    // Increase the height of the element by 50px
    return (height += 50) + 'px';
});

If no unit is provided pixels will be set.

# $el.hide

Hide each matching selection

Hide works by adding the js-hide class which applies display: none !important;

import $ from 'wee-dom';

$('ref:element').hide();

# $el.html

Get inner HTML of first selection or set each matching selection's HTML

<div data-ref="element">
    <h1>Heading</h1>
</div>

# Get

import $ from 'wee-dom';

$('ref:element').html();

<h1>Heading</h1>

# Set

import $ from 'wee-dom';

$('ref:element').html('<h2>New Heading</h2>');

# Function

The current index and HTML are injected into the callback. The scope of this is the element.

import $ from 'wee-dom';

$('.js-element').html((el, i, html) => {
    // Return uppercase HTML
    return html.toUpperCase();
});

# $el.index

Get the zero-based index of a matching selection relative to it's siblings

<ul>
    <li></li>
    <li></li>
    <li class="js-last"></li>
</ul>

import $ from 'wee-dom';

$('.js-last').index();

2

# $el.insertAfter

Insert each matching source selection element after each matching target selection

import $ from 'wee-dom';

$('ref:element).insertAfter('.js-element');

# $el.insertBefore

Insert each matching source selection element before each matching target selection

import $ from 'wee-dom';

$('ref:element).insertBefore('.js-element');

# $el.is

Determine if at least one matching selection matches a specified criteria

# Selection

<div class="js-element"></div>

import $ from 'wee-dom';

$('.js-element').is('div');

true

# Function

<ul class="names">
    <li>John Doe</li>
    <li data-hidden="true">Jane Doe</li>
    <li>John Smith</li><li>Jane Smith</li>
</ul>

import $ from 'wee-dom';

$('.names li').is((i, el) => {
    // Check if data-hidden is set to true

    return $(el).is('hidden') === 'true';
});

true

# $el.last

Get the last element of a matching selection

<ul class="names">
    <li>John Doe</li>
    <li>John Smith</li>
    <li>Jane Doe</li>
    <li>Jane Smith</li>
</ul>

import $ from 'wee-dom';

$('.names li').last();

<li>Jane Smith</li>

<div class='js-selection'>Hello</div>
<div class='js-selection'>World</div>

import $ from 'wee-dom';

$('.js-selection').map((el) => {
    return el.textContent;
});

['Hello', 'World']

# $el.next

Get the unique next sibling of each matching selection

# Simple

import $ from 'wee-dom';

$('ref:element').next();

# Filtered

<ul>
    <li>John Doe</li>
    <li>John Smith</li>
    <li data-ref="name">Jane Doe</li>
    <li>Jane Smith</li>
</ul>

import $ from 'wee-dom';

$('ref:name').next();

<li>Jane Smith</li>

# $el.not

Returns elements not matching the filtered selection

# Selection

import $ from 'wee-dom';

$('ref:element').not('div');

# Function

The current index and element are injected into the callback. The scope of this is the element.

<ul class="names">
    <li>John Doe</li>
    <li data-hidden="true">Jane Doe</li>
    <li>John Smith</li><li>Jane Smith</li>
</ul>

import $ from 'wee-dom';

$('.names li').not((i, el) => {
    // Check if data-hidden is set to truereturn $(el).data('hidden') === true;
});

[<li>John Doe</li>, <li>John Smith</li>, <li>Jane Smith</li>]

# $el.offset

Get the offset position of a matching selection relative to the document

# Set

import $ from 'wee-dom';

$('ref:element').offset({
    top: 100,
    left: 20
});

# Get

import $ from 'wee-dom';

$('ref:element').offset();

{
    top: 520,
    left: 30
}

The object values are returned as unitless pixel values.

# $el.parent

Get unique parent from each matching selection

# Selection Parent

import $ from 'wee-dom';

$('ref:element').parent();

# Filtered

Return selection parent only if it matches the filter.

import $ from 'wee-dom';

$('ref:element').parent('main');

# $el.parents

Get unique ancestors of each matching selection

import $ from 'wee-dom';

$('ref:element').parents();

# $el.position

Get the position of the first matching selection relative to its offset parent

import $ from 'wee-dom';

$('ref:element').position();

{
    top: 250,
    left: 30
}

The object values are returned as unitless pixel values.

# $el.prepend

Prepend selection or markup before each matching selection

# Selection

import $ from 'wee-dom';

$('ref:element').prepend($('.js-element'));

# Function

The current index and HTML are injected into the callback. The scope of this is the element.

<h1 data-ref="listHeading">Names</h1>
<ul data-ref="list">
    <li>John Doe</li>
    <li>Jane Doe</li>
</ul>

import $ from 'wee-dom';

$('ref:listHeading').prepend(() => {
    return $('ref:list').children().d + ' ';
});

<h1 data-ref="listHeading">2 Names</h1>
<ul data-ref="list">
    <li>John Doe</li>
    <li>Jane Doe</li>
</ul>

# $el.prev

Get the unique previous sibling of each matching selection

# Simple

import $ from 'wee-dom';

$('ref:element').prev();

# Filtered

<ul>
    <li>John Doe</li>
    <li>John Smith</li>
    <li data-ref="name">Jane Doe</li>
    <li>Jane Smith</li>
</ul>

import $ from 'wee-dom';

$('ref:name').prev();

<li>John Smith</li>

# $el.prop

Get property of first matching selection or set property of each matching selection

# Get

import $ from 'wee-dom';

$('ref:element').prop('checked');

true

# Single

import $ from 'wee-dom';

$('ref:element').prop('checked', true);

# Multiple

import $ from 'wee-dom';

$('ref:element').prop({
    checked: true,
    required: false
});

# $el.remove

Remove each matching selection from the document

import $ from 'wee-dom';

$('ref:element').remove();

# $el.removeAttr

Remove specified attribute of each matching selection

import $ from 'wee-dom';

$('ref:element').removeAttr('title');

# $el.removeClass

Remove classes from each matching selection

# Single

import $ from 'wee-dom';

$('ref:element').removeClass('modifier');

# Multiple

Separate multiple class names with spaces.

import $ from 'wee-dom';

$('ref:element')removeClass('modifier modifier2');

# Function

The current index and class value are injected into the callback. The scope of this is the element.

import $ from 'wee-dom';

$('ref:element')removeClass((i, className) => {
    // Remove an indexed classreturn className + i;
});

# $el.replaceWith

Replace each matching selection with selection or markup

# Selection

import $ from 'wee-dom';

$('ref:element').replaceWith($('.js-element'));

# Markup

import $ from 'wee-dom';

$('ref:element').replaceWith('<span>Replacement element</span>');

# Function

The current index and HTML are injected into the callback. The scope of this is the element.

<ul class="names">
    <li>John Doe</li>
    <li>Jane Doe</li>
</ul>

import $ from 'wee-dom';

$('.names li').replaceWith((i, html) => {
    return `<li>The ${html}</li>`;
});

<ul class="names">
    <li>The Jane Doe</li>
    <li>The John Doe</li>
</ul>

# $el.reverse

Reverse order of selection results

import $ from 'wee-dom';

$('.js-element').reverse();

# $el.scrollLeft

Get or set the X scroll position of each matching selection

# Get Value

import $ from 'wee-dom';

$('ref:element').scrollLeft();

0

The value returned is a unitless pixel value.

# Set Value

import $ from 'wee-dom';

$('ref:element').scrollLeft(15);

Scroll position should be provided as unitless pixel value.

# $el.scrollTop

Get or set the Y scroll position of each matching selection

import $ from 'wee-dom';

$('ref:element').scrollTop();

1560

The value returned is a unitless pixel value.

# Set Value

import $ from 'wee-dom';

$('body').scrollTop(15);

Scroll position should be provided as unitless pixel value.

# $el.serializeForm

Serialize input values from first matching form selection

# Standard

import $ from 'wee-dom';

$('ref:element').serializeForm();

"inputName=value&inputName2=value2"

# JSON

import $ from 'wee-dom';

$('ref:element').serializeForm(true);

{
    inputName: "value",
    inputName2: "value2"
}

# $el.show

Show each matching selection

Show works by removing the js-hide class either set manually or through $el.hide().

import $ from 'wee-dom';

$('ref:element').show();

# $el.siblings

Get unique siblings of each matching selection

<p>Sibling paragraph</p>
<span>Sibling span</span>
<div data-ref="sibling">Target div.</div>

# All Siblings

Without a filter all siblings will be returned.

import $ from 'wee-dom';

$('ref:sibling').siblings();

[<p>Sibling paragraph</p>, <span>Sibling span</span>]

# Filtered

import $ from 'wee-dom';

$(ref:sibling).siblings('p');

[<p>Sibling paragraph</p>]

# $el.slice

Get subset of selection matches from specified range

import $ from 'wee-dom';

$('li').slice(0, 3);

# $el.text

Get inner text of first selection or set each matching selection's text

<div class="js-element">Inner text</div>

# Get

import $ from 'wee-dom';

$('.js-element').text();

"Inner text"

# Set

import $ from 'wee-dom';

$('.js-element').text('New text');

# Function

The current index and text are injected into the callback. The scope of this is the element.

import $ from 'wee-dom';

$('.js-element').text((el, i, text) => {
    // Return uppercase text
    return text.toUpperCase();
});

# $el.toArray

Cast selection to array

import $ from 'wee-dom';

$('.js-elements').toArray();

# $el.toggle

Toggle the display of each matching selection

Rotates calling the hide and show methods.

import $ from 'wee-dom';

$(ref:element').toggle();

# $el.toggleClass

Toggle adding and removing class(es) from the specified element

# Single

import $ from 'wee-dom';

$('ref:element').toggleClass('modifier');

# Multiple

Separate multiple class names with spaces.

import $ from 'wee-dom';

$('ref:element').toggleClass('modifier modifier2');

# Function

The current index, class value and state are injected into the callback. The scope of this is the element.

import $ from 'wee-dom';

$('.element').toggleClass((i, className, state) => {
    // Return the class intended for toggle
    return className + (state === true ? '-on' : '-off');
});

# $el.val

Get value of first matching selection or set values of each matching selection

# Get

import $ from 'wee-dom';

$('ref:element').val();

# Set

import $ from 'wee-dom';

$('ref:element').val('123');

# Function

The current index and value are injected into the callback. The scope of this is the element.

<input type="text"value="This is an ordinary sentence in an input field." data-ref="input">

import $ from 'wee-dom';

$('ref:input').val((i, value) => {
    // Check the length of the current value but don't change the value
    if (value.length > 20) {
        alert('Getting long winded, aren\'t we?');
    }

    return value;
});

# $el.width

Get or set the width of each matching selection

# Get

import $ from 'wee-dom';

$('ref:element').width();

100

The value returned is a unitless pixel value.

# Set

import $ from 'wee-dom';

$('ref:element').width('10rem');

# Function

The current index and width are injected into the callback. The scope of this is the element.

<div data-ref="example" style="width: 100px;"></div>

import $ from 'wee-dom';

$('ref:example').width((i, width) => {
    // Increase the width of the element by 50px

    return (width += 50) + 'px';
});

If no unit is provided pixels will be set.

# $el.wrap

Wrap markup around each matching selection

# Markup

import $ from 'wee-dom';

$('ref:element').wrap('<div class="wrapper"></div>');

# Function

The current index is injected into the callback. The scope of this is the element.

<div class="library">
    <ul class="books programming">
        <li>JavaScript: The Definitive Guide</li>
        <li>Mastering Regular Expressions</li>
    </ul>
    <ul class="books technique">
        <li>Code Complete</li>
        <li>The Pragmatic Programmer</li>
    </ul>
</div>

import $ from 'wee-dom';

$('.books').wrap(function(i) {
    if ($(this).hasClass('programming')) {
        return '<div class="reference"></div>'
    } else {
        return '<div class="readers"></div>'
    }
});

<div class="library">
    <div class="reference">
        <ul class="books programming">
            <li>JavaScript: The Definitive Guide</li>
            <li>Mastering Regular Expressions</li>
        </ul>
    </div>
    <div class="readers">
        <ul class="books technique">
            <li>Code Complete</li>
            <li>The Pragmatic Programmer</li>
        </ul>
    </div>
</div>

# $el.wrapInner

Wrap markup around the content of each matching selection

# Markup

import $ from 'wee-dom';

$('ref:element').wrapInner('<div class="wrapper"></div>);

# Function

The current index is injected into the callback. The scope of this is the element.

<ul class="names">
    <li class="boss">Jane Doe</li>
    <li>John Doe</li>
</ul>

import $ from 'wee-dom';

$('.names li').wrapInner(function(i) {
    // Wrap bosses in bold tag
    if ($(this).hasClass('boss')) {
        return'<b></b>';
    }
});

<ul class="names">
    <li class="boss"><b>Jane Doe</b></li>
    <li>John Doe</li>
</ul>