element.classList

La propriété en lecture seule Element.classList retourne une collection directe  DOMTokenList des attributs de classe de l'élément.

L'utilisation de classList est une alternative à la propriété element.className qui renvoie une chaine composée de la liste des classes, séparées par des espaces.

Syntaxe

const elementClasses = elementNodeReference.classList;

elementClasses est une DOMTokenList représentant l'attribut class de elementNodeReference. Si l'attribut class n'a pas été défini ou est vide elementClasses.length retourne 0. element.classList est en lecture seule. Pour la modifier il convient d'utiliser les méthodes add() et remove().

Méthodes

add( String [, String] )
Ajoute les classes spécifiées. Si une classe est déjà assignée en attribut de cet élément, elle est ignorée.
remove( String [, String] )
Supprime les classes spécifiées.
Note: Supprimer une classe qui n'existe pas NE génère PAS d'erreurs.
item( Number )
Renvoie la position d'une classe dans une collection.
toggle( String [, force] )
Si un seul argument est présent : change la présence d'une classe dans la liste. Si la classe existe, alors la supprime et renvoie false, dans le cas inverse, ajoute cette classe et retourne true.
Si le second argument est présent : Si l'argument force est à true, ajoute cette classe, si l'argument est à false, la supprime.
contains( String )
Vérifie si la classe spécifiée est présente dans la liste des classes attribuées à cet élément.
replace( oldClass, newClass )
Remplace une classe par une autre.

Exemples

const div = document.createElement('div');
div.className = 'foo';

// notre point de départ: <div class="foo"></div>
console.log(div.outerHTML);

// utiliser l'API classList pour supprimer et ajouter des classes
div.classList.remove("foo");
div.classList.add("anotherclass");

// <div class="anotherclass"></div>
console.log(div.outerHTML);

// si "visible" est défini, le supprimer, sinon, l'ajouter
div.classList.toggle("visible");

// ajouter/supprimer "visible", en fonction d'un test conditionnel, pour i inférieur à 10
div.classList.toggle("visible", i < 10 );

console.log(div.classList.contains("foo"));

// ajouter ou supprimer plusieurs classes
div.classList.add("foo", "bar", "baz");
div.classList.remove("foo", "bar", "baz");

// ajouter ou supprimer plusieurs classes en utilisant la syntaxe de propagation
const cls = ["foo", "bar"];
div.classList.add(...cls); 
div.classList.remove(...cls);

// remplacer la classe "foo" par la classe "bar"
div.classList.replace("foo", "bar");

Les versions de Firefox antérieures à la 26 n'implémentent pas l'utilisation de plusieurs arguments dans les méthodes add/remove/toggle. Voir https://bugzilla.mozilla.org/show_bug.cgi?id=814014

Prothèse d'émulation

L'ancien événement onpropertychange peut être utilisé pour créer une maquette classList vivante grâce à une propriété Element.prototype.className qui déclenche l'événement spécifié une fois qu'il est modifié.

La polyfill suivante pour classList et DOMTokenList garantit une conformité totale (couverture) pour toutes les méthodes et propriétés standard de Element.prototype.classList pour les navigateurs IE10-IE11 ainsi qu'un comportement quasi conforme pour IE 6-9. Consultez ce qui suit :

// 1. String.prototype.trim polyfill
if (!"".trim) String.prototype.trim = function(){ return this.replace(/^[\s]+|[\s]+$/g, ''); };
(function(window){"use strict"; // prevent global namespace pollution
if(!window.DOMException) (DOMException = function(reason){this.message = reason}).prototype = new Error;
var wsRE = /[\11\12\14\15\40]/, wsIndex = 0, checkIfValidClassListEntry = function(O, V) {
  if (V === "") throw new DOMException(
    "Failed to execute '" + O + "' on 'DOMTokenList': The token provided must not be empty." );
  if((wsIndex=V.search(wsRE))!==-1) throw new DOMException("Failed to execute '"+O+"' on 'DOMTokenList': " +
    "The token provided ('"+V[wsIndex]+"') contains HTML space characters, which are not valid in tokens.");
}
// 2. Implement the barebones DOMTokenList livelyness polyfill
if (typeof DOMTokenList !== "function") (function(window){
    var document = window.document, Object = window.Object, hasOwnProp = Object.prototype.hasOwnProperty;
    var defineProperty = Object.defineProperty, allowTokenListConstruction = 0, skipPropChange = 0;
    function DOMTokenList(){
        if (!allowTokenListConstruction) throw TypeError("Illegal constructor"); // internally let it through
    }
    DOMTokenList.prototype.toString = DOMTokenList.prototype.toLocaleString = function(){return this.value};
    DOMTokenList.prototype.add = function(){
        a: for(var v=0, argLen=arguments.length,val="",ele=this[" uCL"],proto=ele[" uCLp"]; v!==argLen; ++v) {
            val = arguments[v] + "", checkIfValidClassListEntry("add", val);
            for (var i=0, Len=proto.length, resStr=val; i !== Len; ++i)
                if (this[i] === val) continue a; else resStr += " " + this[i];
            this[Len] = val, proto.length += 1, proto.value = resStr;
        }
        skipPropChange = 1, ele.className = proto.value, skipPropChange = 0;
    };
    DOMTokenList.prototype.remove = function(){
        for (var v=0, argLen=arguments.length,val="",ele=this[" uCL"],proto=ele[" uCLp"]; v !== argLen; ++v) {
            val = arguments[v] + "", checkIfValidClassListEntry("remove", val);
            for (var i=0, Len=proto.length, resStr="", is=0; i !== Len; ++i)
                if(is){ this[i-1]=this[i] }else{ if(this[i] !== val){ resStr+=this[i]+" "; }else{ is=1; } }
            if (!is) continue;
            delete this[Len], proto.length -= 1, proto.value = resStr;
        }
        skipPropChange = 1, ele.className = proto.value, skipPropChange = 0;
    };
    window.DOMTokenList = DOMTokenList;
    function whenPropChanges(){
        var evt = window.event, prop = evt.propertyName;
        if ( !skipPropChange && (prop==="className" || (prop==="classList" && !defineProperty)) ) {
            var target = evt.srcElement, protoObjProto = target[" uCLp"], strval = "" + target[prop];
            var tokens=strval.trim().split(wsRE), resTokenList=target[prop==="classList"?" uCL":"classList"];
            var oldLen = protoObjProto.length;
            a: for(var cI = 0, cLen = protoObjProto.length = tokens.length, sub = 0; cI !== cLen; ++cI){
                for(var innerI=0; innerI!==cI; ++innerI) if(tokens[innerI]===tokens[cI]) {sub++; continue a;}
                resTokenList[cI-sub] = tokens[cI];
            }
            for (var i=cLen-sub; i < oldLen; ++i) delete resTokenList[i]; //remove trailing indexs
            if(prop !== "classList") return;
            skipPropChange = 1, target.classList = resTokenList, target.className = strval;
            skipPropChange = 0, resTokenList.length = tokens.length - sub;
        }
    }
    function polyfillClassList(ele){
        if (!ele || !("innerHTML" in ele)) throw TypeError("Illegal invocation");
        ele.detachEvent( "onpropertychange", whenPropChanges ); // prevent duplicate handler infinite loop
        allowTokenListConstruction = 1;
        try{ function protoObj(){} protoObj.prototype = new DOMTokenList(); }
        finally { allowTokenListConstruction = 0 }
        var protoObjProto = protoObj.prototype, resTokenList = new protoObj();
        a: for(var toks=ele.className.trim().split(wsRE), cI=0, cLen=toks.length, sub=0; cI !== cLen; ++cI){
            for (var innerI=0; innerI !== cI; ++innerI) if (toks[innerI] === toks[cI]) { sub++; continue a; }
            this[cI-sub] = toks[cI];
        }
        protoObjProto.length = cLen-sub, protoObjProto.value = ele.className, protoObjProto[" uCL"] = ele;
        if (defineProperty) { defineProperty(ele, "classList", { // IE8 & IE9 allow defineProperty on the DOM
            enumerable:   1, get: function(){return resTokenList},
            configurable: 0, set: function(newVal){
                skipPropChange = 1, ele.className = protoObjProto.value = (newVal += ""), skipPropChange = 0;
                var toks = newVal.trim().split(wsRE), oldLen = protoObjProto.length;
                a: for(var cI = 0, cLen = protoObjProto.length = toks.length, sub = 0; cI !== cLen; ++cI){
                    for(var innerI=0; innerI!==cI; ++innerI) if(toks[innerI]===toks[cI]) {sub++; continue a;}
                    resTokenList[cI-sub] = toks[cI];
                }
                for (var i=cLen-sub; i < oldLen; ++i) delete resTokenList[i]; //remove trailing indexs
            }
        }); defineProperty(ele, " uCLp", { // for accessing the hidden prototype
            enumerable: 0, configurable: 0, writeable: 0, value: protoObj.prototype
        }); defineProperty(protoObjProto, " uCL", {
            enumerable: 0, configurable: 0, writeable: 0, value: ele
        }); } else { ele.classList=resTokenList, ele[" uCL"]=resTokenList, ele[" uCLp"]=protoObj.prototype; }
        ele.attachEvent( "onpropertychange", whenPropChanges );
    }
    try { // Much faster & cleaner version for IE8 & IE9:
        // Should work in IE8 because Element.prototype instanceof Node is true according to the specs
        window.Object.defineProperty(window.Element.prototype, "classList", {
            enumerable: 1,   get: function(val){
                                 if (!hasOwnProp.call(this, "classList")) polyfillClassList(this);
                                 return this.classList;
                             },
            configurable: 0, set: function(val){this.className = val}
        });
    } catch(e) { // Less performant fallback for older browsers (IE 6-8):
        window[" uCL"] = polyfillClassList;
        // the below code ensures polyfillClassList is applied to all current and future elements in the doc.
        document.documentElement.firstChild.appendChild(document.createElement('style')).styleSheet.cssText=(
            '_*{x-uCLp:expression(!this.hasOwnProperty("classList")&&window[" uCL"](this))}' + //  IE6
            '[class]{x-uCLp/**/:expression(!this.hasOwnProperty("classList")&&window[" uCL"](this))}' //IE7-8
        );
    }
})(window);
// 3. Patch in unsupported methods in DOMTokenList
(function(DOMTokenListProto, testClass){
    if (!DOMTokenListProto.item) DOMTokenListProto.item = function(i){
        function NullCheck(n) {return n===void 0 ? null : n} return NullCheck(this[i]);
    };
    if (!DOMTokenListProto.toggle || testClass.toggle("a",0)!==false) DOMTokenListProto.toggle=function(val){
        if (arguments.length > 1) return (this[arguments[1] ? "add" : "remove"](val), !!arguments[1]);
        var oldValue = this.value;
        return (this.remove(oldValue), oldValue === this.value && (this.add(val), true) /*|| false*/);
    };
    if (!DOMTokenListProto.replace || typeof testClass.replace("a", "b") !== "boolean")
        DOMTokenListProto.replace = function(oldToken, newToken){
            checkIfValidClassListEntry("replace", oldToken), checkIfValidClassListEntry("replace", newToken);
            var oldValue = this.value;
            return (this.remove(oldToken), this.value !== oldValue && (this.add(newToken), true));
        };
    if (!DOMTokenListProto.contains) DOMTokenListProto.contains = function(value){
        for (var i=0,Len=this.length; i !== Len; ++i) if (this[i] === value) return true;
        return false;
    };
    if (!DOMTokenListProto.forEach) DOMTokenListProto.forEach = function(f){
        if (arguments.length === 1) for (var i = 0, Len = this.length; i !== Len; ++i) f( this[i], i, this);
        else for (var i=0,Len=this.length,tArg=arguments[1]; i !== Len; ++i) f.call(tArg, this[i], i, this);
    };
    if (!DOMTokenListProto.entries) DOMTokenListProto.entries = function(){
        var nextIndex = 0, that = this;
        return {next: function() {
            return nextIndex<that.length ? {value: [nextIndex, that[nextIndex++]], done: false} : {done: true};
        }};
    };
    if (!DOMTokenListProto.values) DOMTokenListProto.values = function(){
        var nextIndex = 0, that = this;
        return {next: function() {
            return nextIndex<that.length ? {value: that[nextIndex++], done: false} : {done: true};
        }};
    };
    if (!DOMTokenListProto.keys) DOMTokenListProto.keys = function(){
        var nextIndex = 0, that = this;
        return {next: function() {
            return nextIndex<that.length ? {value: nextIndex++, done: false} : {done: true};
        }};
    };
})(window.DOMTokenList.prototype, window.document.createElement("div").classList);
})(window);

Mise en garde

La prothèse d'émulation est limitée dans sa fonctionnalité. Elle est actuellement incapable de traiter les éléments hors document (par exemple, les éléments créés par document.createElement avant d'être ajoutés à un nœud parent) dans IE6-7.

Cependant, elle devrait très bien fonctionner dans IE9. Une différence majeure entre la version prothésée de classList et les spécifications du W3 est que pour IE6-8, il n'y a pas moyen de créer un objet immuable (un objet dont les propriétés ne peuvent pas être directement modifiées). Dans IE9, en revanche, c'est possible en étendant le prototype, en gelant l'objet visible et en écrasant les méthodes de propriétés natives. Cependant, de telles actions ne fonctionneraient pas dans IE6-IE8 et, dans IE9, elles ralentiraient la performance de la page web entière au point de la faire ramper, rendant ces modifications complètement impraticables pour cette prothèse d'émulation.

Une note mineure est que dans IE6-7, cette prothèse utilise la propriété window[" uCL"] de l'objet window pour communiquer avec les expressions CSS, la propriété css x-uCLp sur tous les éléments, et la propriété element[" uCL"] sur tous les éléments pour permettre la collecte des déchets et augmenter les performances. Dans tous les navigateurs prothésés (IE6-9), une propriété element[" uCLp"] supplémentaire est ajoutée à l'élément pour garantir un prototypage conforme aux normes, et une propriété DOMTokenList[" uCL"] est ajoutée à chaque objet element["classList"] pour garantir que la DOMTokenList est liée à son propre élément.

Spécifications

Spécification Statut Commentaire
HTML Living Standard
La définition de 'Element.classList' dans cette spécification.
Standard évolutif Note dans la spécification HTML relative à l'attribut class.
DOM
La définition de 'Element.classList' dans cette spécification.
Standard évolutif Définition initiale.
DOM4
La définition de 'Element.classList' dans cette spécification.
Obsolete

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung Internet
classListChrome Support complet 8Edge Support complet 16
Support complet 16
Aucun support 12 — 16
Notes
Notes Not supported for SVG elements.
Firefox Support complet 3.6IE Support partiel 10
Notes
Support partiel 10
Notes
Notes Not supported for SVG elements.
Opera Support complet 11.5Safari Support complet 6WebView Android Support complet ≤37Chrome Android Support complet 18Firefox Android Support complet 4Opera Android Support complet 11.5Safari iOS Support complet 5Samsung Internet Android Support complet 1.0
Multiple arguments for add() & remove()Chrome Support complet 24Edge Support complet 12Firefox Support complet 26IE Aucun support NonOpera Support complet 15Safari Support complet 7WebView Android Support complet ≤37Chrome Android Support complet 25Firefox Android Support complet 26Opera Android Support complet 14Safari iOS Support complet 7Samsung Internet Android Support complet 1.5
replace()Chrome Support complet 61Edge Support complet 17Firefox Support complet 49IE Aucun support NonOpera ? Safari Aucun support NonWebView Android Support complet 61Chrome Android Support complet 61Firefox Android Support complet 49Opera Android ? Safari iOS Aucun support NonSamsung Internet Android Support complet 8.0
toggle() method's second argumentChrome Support complet 24Edge Support complet 12Firefox Support complet 24IE Aucun support NonOpera Support complet 15Safari Support complet 7WebView Android Support complet OuiChrome Android Support complet OuiFirefox Android Support complet 24Opera Android ? Safari iOS Support complet 7Samsung Internet Android Support complet Oui

Légende

Support complet  
Support complet
Support partiel  
Support partiel
Aucun support  
Aucun support
Compatibilité inconnue  
Compatibilité inconnue
Voir les notes d'implémentation.
Voir les notes d'implémentation.

Voir aussi