@wordpress/token-list Edit

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

Installation 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.

Top ↑

Usage 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.

Top ↑

Browser Support 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.

Code is Poetry.

Skip to toolbar