Domassist

A collection of functions designed to make working the DOM easier

Download from GitHub

This is a collection of functions designed to make working the DOM easier.

Installation

npm install --save domassist

Usage

In your project import the library:

import domassist from 'domassist'

The first argument for each method you are interested in is either a selector, DOM node, or a collection of DOM Nodes.

const els = domassist.find('.my-class');
domassist.addClass(els, 'my-new-class');

API

Find elements on the page based on a valid CSS selector.

Parameters:

selector - {string|Element|NodeList} - A valid CSS selector. If a NodeList is passed it will be converted to an Array.

[context] - Where to start looking for the selector.

Returns:

Array - If no element is found, an empty array is returned.

Example:

domassist.find('p'); // find all paragraph tags
domassist.find('[type="text"]', document.forms[0]); // find all text fields in the first form

Find a single element on a page. If more than one element is found for a selector, the first instance is returned.

If no element is found, null is returned

Parameters:

selector - {string} A valid CSS selector

[context] - Where to start looking for the selector.

Returns:

Element|null - If no element is found null is returned.

Add one or more classes to an element(s). For multiple classes pass an array.

Parameters:

selector - {string|Element|NodeList} - A valid CSS selector. If a NodeList is passed it will be converted to an Array.

classes - {string|Array} The class or classes to add.

Returns:

Array - An array of elements that classes were applied to.

Example:

domassist.addClass('.my-div', 'new-class');
domassist.addClass('.my-div', ['class-1', 'class-2', 'class-3']);

Remove one or more classes to an element(s). For multiple classes, pass an array.

Parameters:

selector - {string|Element|NodeList} - A valid CSS selector. If a NodeList is passed it will be converted to an Array.

classes - {string|Array} The class or classes to add.

Returns:

Array - An array of elements that classes were applied to.

Example:

domassist.removeClass('.my-div', 'new-class');
domassist.removeClass('.my-div', ['class-1', 'class-2', 'class-3']);

Add a class if it doesn't exist and vice versa if it does.

Parameters:

selector - {string|Element} - A valid CSS selector. If a NodeList is passed it will be converted to an Array.

class - {string} The class to toggle.

Example:

// new-class does not exist on element
domassist.toggleClass('.my-div', 'new-class'); // class added
domassist.toggleClass('.my-div', 'new-class'); // class removed

Find out if an element has a class assigned or not.

Parameters:

selector - {string|Element} - A valid CSS selector.

class - {string} - The class to check for.

Returns:

Boolean - True is returned if the class exist.

Update inner HTML of an element.

Parameters:

selector - {string|Element|NodeList} - A valid CSS selector, HTML element, or.

classes - {string|Array} The class or classes to add.

Example:

domassist.html('.my-div', 'hello world'); // add html
domassist.html('.my-div', ''); // remove html

Find the closest parent element that matches the given selector

Parameters:

element - {Element} the element where you want to start looking from

selector - {string} A valid CSS of the element to be found.

Hide an element by setting it's css display to none.

Parameters:

selector - {string|Element|NodeList}

Easy way to add callbacks to the mouseenter and mouseleave events.

Parameters:

element - {Element}

enter - {function} Callback to fire when user moves mouse over the supplied element.

exit - {function} Callback to fire when user moves mouse off the supplied element.

Examples:

domassist.hover('.my-div', (e) => {
  console.log('mouse over');
}, (e) => {
  console.log('mouse out');
});

Modify many parts of an element at once such as adding and removing classes, changing the element's html, or attaching events.

Parameters:

selector - {string|Element|NodeList}

params - {object} An object of key:value pairs of what element parameters to change.

Examples:

domassist.modify('.my-div', {
  addClass: 'testing',
  html: 'hello world',
  events: {
    click: (e) => {
      // do something
    },
    mouseenter: (e) => {
      // do something
    },
    mouseleave: (e) => {
      // do something
    }
  },
  styles: {
    width: '100px',
    height: '150px',
  }
});

Attach an event to an element based on a valid CSS selector or an Element.

Parameters:

selector - {string|Element|NodeList}

event - {string} The name of the event to attach such as click, mouseenter, or touchend

callback - {function} A function to be called when the supplied event is triggered.

[capture = false] - {Boolean} Determines which phase to the attach the event to. Default is false when means the event is attached to the bubble phase. If true then it's attached to the capture phase.

Example:

domassist.on('a', 'click', (e) => {
  e.preventDefault();
  console.log('clicked!');
});

Remove an attached event.

Parameters

selector - {string|Element|NodeList}

event - {string} The name of the event to remove such as click, mouseenter, or touchend

Example:

domassist.off('a', 'click');

Attach an event to an element to be fired once.

Parameters:

selector - {Element}

event - {string} The name of the event to attach such as click, mouseenter, or touchend

callback - {function} A function to be called when the supplied event is triggered.

[capture = false] - {Boolean} Determines which phase to the attach the event to. Default is false when means the event is attached to the bubble phase. If true then it's attached to the capture phase.

Example:

domassist.once('a', 'click', (e) => {
  e.preventDefault();
  console.log('clicked!');
});

Add a function to be called once the DOMContentLoaded event is fired. This is when the entire DOM has been finished downloading. You'll want to use this method to execute javascript on page load. You can call this method many times throughout your application allowing you to add multiple callbacks.

Parameters:

callback - {function} The function to be called once the page has finished loading.

Example:

domassist.ready(() => {
  const x = 1;
  console.log('x is', x);
});
domassist.ready(() => {
  const x = 2;
  console.log('x is', x);
});
domassist.ready(() => {
  const x = 3;
  console.log('x is', x);
});
// x is 1
// x is 2
// x is 3

Show an element by setting an element's display to it's default display type.

Parameters:

selector - {string|Element|NodeList}

Apply css styles to an element(s).

Parameters:

selector - {string|Element|NodeList}

styles - {object} CSS styles as a key:value pair, ex { width: '100px', height: '100px'}.

Example

domassist.styles('p', {
  width: '100px',
  height: '150px'
});

Add attributes to elements. If an attribute that is passed is not a valid attribute for the element it will be added as a data-* attribute.

Parameters:

selector - {string|Element|NodeList} The element(s) to apply new attributes to.

attributes - {object} An object of attributes

Example:

domassist.addAttrs('.my-div', {
  id: 'anchor-id',
  title: 'this is a title',
  href: 'http://google.com',
  testAttr: 'data attribute',
});
domassist.addAttrs('a', {
  id: 'anchor-id',
  title: 'this is a title',
  href: 'http://google.com',
  testAttr: 'data attribute',
});
// <div class="my-div" id="anchor-id" title="this is a title" data-href="http://www.google.com" data-test-attr="data attribute"></div>
// <a class="my-div" id="anchor-id" title="this is a title" href="http://www.google.com" data-test-attr="data attribute"></a>