Element : méthode setAttribute()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

La méthode setAttribute(), rattachée à l'interface Element, ajoute un nouvel attribut ou change la valeur d'un attribut existant en utilisant la valeur fournie. Si l'attribut existe déjà, la valeur est mise à jour ; sinon, un nouvel attribut est ajouté avec le nom et la valeur spécifiés.

Pour obtenir la valeur actuelle d'un attribut, on utilisera la méthode getAttribute() ; pour supprimer un attribut, on emploiera removeAttribute().

Si besoin de travailler sur le nœud Attr avant de l'ajouter (par exemple en le clonant depuis un autre élément), on pourra utiliser la méthode setAttributeNode() à la place.

Syntaxe

setAttribute(name, value)

Paramètres

name: Une chaîne de caractères spécifiant le nom de l'attribut pour lequel la valeur doit être définie. Cette valeur est automatiquement convertie en minuscules quand setAttribute() est appelée sur un élément HTML dans un document HTML.
value: Une chaîne de caractères contenant la valeur à affecter à l'attribut. Toute valeur spécifiée qui n'est pas une chaîne de caractères, est convertie automatiquement en chaîne de caractères.

Les attributs booléens sont considérés comme true s'ils sont présents sur l'élément, quelle que soit leur valeur réelle. En règle générale, il faut fournir la chaîne vide ("") dans value ou uniquement le nom de l'attribut (sans espace avant ou après) pour indiquer false. Voir l'exemple ci-dessous pour une démonstration pratique.

Puisque la valeur spécifiée est convertie en chaîne, spécifier null fournira un résultat inattendu. Au lieu de supprimer l'attribut ou de définir sa valeur comme null , cette méthode définit à la place la valeur de l'attribut avec la chaîne de caractères "null". Pour supprimer un attribut, on appellera removeAttribute().

Valeur retournée

Aucune (undefined).

Exceptions

InvalidCharacterError DOMException: Levée si la valeur name n'est pas un nom XML valide (par exemple si elle commence par un chiffre, un tiret, un point ou si elle contient des caractères autres que des caractères alphanumériques, des tirets bas, des tirets ou des points).

Exemples

Dans l'exemple suivant, setAttribute() est utilisée pour définir des attributs sur un élément <button>.

HTML

html

<button>Hello World</button>

button {
  height: 30px;
  width: 100px;
  margin: 1em;
}

JavaScript

const button = document.querySelector("button");

button.setAttribute("name", "helloButton");
button.setAttribute("disabled", "");

Cet exemple permet d'illustrer deux choses :

Le premier appel à setAttribute() change la valeur de l'attribut name en "helloButton". Vous pouvez le voir en utilisant l'inspecteur de votre navigateur (Chrome, Edge, Firefox, Safari).
Pour définir la valeur d'un attribut booléen, tel que disabled, on peut fournir n'importe quelle valeur. Une bonne pratique consiste à utiliser la chaîne vide ou le nom de l'attribut. Quelle que soit la valeur fournie, dès qu'elle est présente, elle indique que le booléen sera actif (true). L'absence de l'attribut signifie que sa valeur est false. En utilisant la chaîne vide ("") comme valeur, on passe disabled à l'état true dans le DOM, ce qui entraîne la désactivation du bouton à l'écran.

Spécifications

Specification
DOM # ref-for-dom-element-setattribute①