DOMTokenList.replace()

The replace() method of the DOMTokenList interface replaces an existing token with a new token. If the first token doesn't exist, replace() returns false immediately, without adding the new token to the token list.

Syntax

tokenList.replace(oldToken, newToken);

Parameters

oldToken

A DOMString representing the token you want to replace.

newToken

A DOMString representing the token you want to replace oldToken with.

Return value

A boolean value, which is true if oldToken was successfully replaced, or false if not.

Examples

In the following example we retrieve the list of classes set on a <span> element as a DOMTokenList using Element.classList. We then replace a token in the list, and write the list into the <span>'s Node.textContent.

First, the HTML:

<span class="a b c"></span>

Now the JavaScript:

let span = document.querySelector("span");
let classes = span.classList;

let result = classes.replace("c", "z");
console.log(result);

if (result) {
  span.textContent = classes;
} else {
  span.textContent = 'token not replaced successfully';
}

The output looks like this:

Polyfill

The following polyfill will add the replace method to the DOMTokenList class. The following code will only work with IE10-11. To use with earlier versions of IE, refer to the polyfill at element.classList#Polyfill

DOMTokenList.prototype.replace = function (a, b) {
    if (this.contains(a)) {
        this.add(b);
        this.remove(a);
        return true;
    }
    return false;
}

Specifications

Browser compatibility