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 such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default
in your code.
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
andTokenList#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.
Contributing to this package
This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.
To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.