HTMLOptionsCollection : méthode add()

Baseline

Large disponibilité

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.

Voir la compatibilité complète
En savoir plus

La méthode add() de l'interface HTMLOptionsCollection ajoute un objet HTMLOptionElement ou HTMLOptGroupElement à cette collection HTMLOptionsCollection.

Syntaxe

add(item)
add(item, before)

Paramètres

item: Un objet HTMLOptionElement ou HTMLOptGroupElement.
before Facultatif: Un élément de la collection, ou un indice numérique (commençant à 0) représentant l'élément devant lequel item doit être inséré. S'il est omis, vaut null ou si l'indice n'existe pas, le nouvel élément est ajouté à la fin de la collection.

Exceptions

HierarchyRequestError DOMException: Levée si l'élément item passé à la méthode est un ancêtre de l'élément dans lequel il doit être inséré.

Par défaut, add() ajoute l'élément HTML <option> ou <optgroup> passé en paramètre à la fin de la collection. Vous pouvez définir où l'élément <option> ou <optgroup> ajouté doit être placé en définissant le paramètre before. Le paramètre before est l'élément <option> ou un indice numérique (commençant à 0) de l'élément <option> que l'élément ajouté doit précéder.

Si le paramètre before est null, hors limites (ou omis), l'élément <option> ou <optgroup> sera ajouté en dernier dans la collection, hors de tout <optgroup>. Si l'élément <option> référencé par le paramètre before se trouve dans un <optgroup>, un HTMLOptionElement ajouté sera dans le même groupe.

L'élément <optgroup> ne peut contenir que des éléments <option> comme nœuds enfants. La méthode add() ajoutera avec succès un HTMLOptGroupElement à la fin de la collection HTMLOptionsCollection ou entre des éléments <optgroup> uniquement. Autrement dit, tenter d'ajouter un HTMLOptGroupElement avant un élément <option> à l'intérieur d'un groupe d'options (<optgroup>) peut échouer silencieusement si l'option (<option>) référencée par le paramètre before n'est pas la première option (<option>) de son groupe (<optgroup>).

Exemples

const optionList = document.querySelector("select").options;
const firstOption = document.createElement("option");
firstOption.text = "nouvel élément";
optionList.add(firstOption, 0); // ajouté en premier
optionList.add(optionList[0]); // déplace le premier élément à la fin