Token List

Constructable, plain JavaScript DOMTokenList implementation, supporting non-browser runtimes.

Installation

Install the module

npm install @wordpress/token-list

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Usage

Construct a new token list, optionally with an initial value. A value with an interface matching DOMTokenList is returned.

import TokenList from '@wordpress/token-list';

const tokens = new TokenList( 'abc def' );
tokens.add( 'ghi' );
tokens.remove( 'def' );
tokens.replace( 'abc', 'xyz' );
console.log( tokens.value );
// "xyz ghi"

All methods of DOMTokenList are implemented.

Note the following implementation divergences from the specification:

• TokenList#supports will always return true, regardless of the token passed.
• TokenList#add and TokenList#remove will simply disregard the empty string argument or whitespace of a token argument, rather than throwing an error.
• An item cannot be referenced by its index as a property. Use TokenList#item instead.

Browser Support

While it could be used in one's implementation, this is not intended to serve as a polyfill for Element#classList or other instances of DOMTokenList.

The implementation of the DOMTokenList interface provided through @wordpress/token-list is broadly compatible in environments supporting ES5 (IE8 and newer). That being said, due to its internal implementation leveraging arrays for TokenList#entries, TokenList#forEach, TokenList#keys, and TokenList#values, you may need to assure that these functions are supported or polyfilled if you intend to use them.

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries#Browser_compatibility
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values#Browser_compatibility

TokenList's own internal implementation of the DOMTokenList interface does not leverage any of these functions, so it is not necessary to polyfill them for basic usage.