API.md

Modules

once-dom

Mark DOM elements as processed to prevent multiple initializations.

Functions

once(id, selector, [context]) ⇒ Array.<Element>

Ensures a JavaScript callback is only executed once on a set of elements.

Filters a NodeList or array of elements, removing those already processed by a callback with a given id. This method adds a data-once attribute on DOM elements. The value of this attribute identifies if a given callback has been executed on that element.

once-dom

Mark DOM elements as processed to prevent multiple initializations.

Example (Use as a module)

<script type="module">
  import once from 'https://unpkg.com/once-dom@latest/dist/once.esm.js';
  const elements = once('my-once-id', 'div');
  // Initialize elements.
  elements.forEach(el => el.innerHTML = 'processed');
</script>

Example (Use as a regular script)

<script src="https://unpkg.com/once-dom@latest/dist/once.min.js"></script>
<script>
  const elements = once('my-once-id', 'div');
  // Initialize elements.
  elements.forEach(el => el.innerHTML = 'processed');
</script>

Example (Using a single element as input)

// once methods always return an array, to simplify the use with a single
// element use destructuring or the shift method.
const [myElement] = once('my-once-id', document.body);
const myElement = once('my-once-id', document.body).shift();

once(id, selector, [context]) ⇒ Array.<Element>

Ensures a JavaScript callback is only executed once on a set of elements.

Filters a NodeList or array of elements, removing those already processed by a callback with a given id. This method adds a data-once attribute on DOM elements. The value of this attribute identifies if a given callback has been executed on that element.

Kind: global function
Returns: Array.<Element> - An array of elements that have not yet been processed by a once call with a given id.

Param	Type	Default	Description
id	string		The id of the once call.
selector	NodeList | Array.<Element> | Element | string		A NodeList or array of elements.
[context]	Document | Element	document	An element to use as context for querySelectorAll.

Example (Basic usage)

const elements = once('my-once-id', '[data-myelement]');

Example (Input parameters accepted)

// NodeList.
once('my-once-id', document.querySelectorAll('[data-myelement]'));
// Array or Array-like of Element.
once('my-once-id', jQuery('[data-myelement]'));
// A CSS selector without a context.
once('my-once-id', '[data-myelement]');
// A CSS selector with a context.
once('my-once-id', '[data-myelement]', document.head);
// Single Element.
once('my-once-id', document.querySelector('#some-id'));

Example (Using a single element)

// Once always returns an array, event when passing a single element. Some
// forms that can be used to keep code readable.
// Destructuring:
const [myElement] = once('my-once-id', document.body);
// By changing the resulting array, es5 compatible.
const myElement = once('my-once-id', document.body).shift();

• once(id, selector, [context]) ⇒ Array.<Element>
  • .remove(id, selector, [context]) ⇒ Array.<Element>
  • .filter(id, selector, [context]) ⇒ Array.<Element>
  • .find([id], [context]) ⇒ Array.<Element>

once.remove(id, selector, [context]) ⇒ Array.<Element>

Removes a once id from an element's data-drupal-once attribute value.

If a once id is removed from an element's data-drupal-once attribute value, the JavaScript callback associated with that id can be executed on that element again.

Kind: static method of once
Returns: Array.<Element> - A filtered array of elements that had been processed by the provided id, and are now able to be processed again.

Param	Type	Default	Description
id	string		The id of a once call.
selector	NodeList | Array.<Element> | Element | string		A NodeList or array of elements to remove the once id from.
[context]	Document | Element	document	An element to use as context for querySelectorAll.

Example (Basic usage)

const elements = once.remove('my-once-id', '[data-myelement]');

Example (Input parameters accepted)

// NodeList.
once.remove('my-once-id', document.querySelectorAll('[data-myelement]'));
// Array or Array-like of Element.
once.remove('my-once-id', jQuery('[data-myelement]'));
// A CSS selector without a context.
once.remove('my-once-id', '[data-myelement]');
// A CSS selector with a context.
once.remove('my-once-id', '[data-myelement]', document.head);
// Single Element.
once.remove('my-once-id', document.querySelector('#some-id'));

once.filter(id, selector, [context]) ⇒ Array.<Element>

Finds elements that have been processed by a given once id.

Behaves like once and remove without changing the DOM. To select all DOM nodes processed by a given id, use find.

Kind: static method of once
Returns: Array.<Element> - A filtered array of elements that have already been processed by the provided once id.

Param	Type	Default	Description
id	string		The id of the once call.
selector	NodeList | Array.<Element> | Element | string		A NodeList or array of elements to remove the once id from.
[context]	Document | Element	document	An element to use as context for querySelectorAll.

Example (Basic usage)

const filteredElements = once.filter('my-once-id', '[data-myelement]');

Example (Input parameters accepted)

// NodeList.
once.filter('my-once-id', document.querySelectorAll('[data-myelement]'));
// Array or Array-like of Element.
once.filter('my-once-id', jQuery('[data-myelement]'));
// A CSS selector without a context.
once.filter('my-once-id', '[data-myelement]');
// A CSS selector with a context.
once.filter('my-once-id', '[data-myelement]', document.head);
// Single Element.
once.filter('my-once-id', document.querySelector('#some-id'));

once.find([id], [context]) ⇒ Array.<Element>

Finds elements that have been processed by a given once id.

Query the 'context' element for elements that already have the corresponding once id value.

Kind: static method of once
Returns: Array.<Element> - A filtered array of elements that have already been processed by the provided once id.

Param	Type	Default	Description
[id]	string		The id of the once call.
[context]	Document | Element	document	Scope of the search for matching elements.

Example (Basic usage)

const oncedElements = once.find('my-once-id');

Example (Input parameters accepted)

// Call without parameters, return all elements with a `data-once` attribute.
once.find();
// Call without a context.
once.find('my-once-id');
// Call with a context.
once.find('my-once-id', document.head);