Dans un document HTML, la méthode  document.createElement() crée un élément HTML du type spécifié par  tagName ou un  HTMLUnknownElement si tagName n'est pas reconnu .

Syntaxe

var element = document.createElement(tagName[, options]);

Paramètres

tagName
Une chaîne de caractères (string) spécifiant le type d'élément à créer. Le nodeName (nom du noeud) de l'élément créé est initialisé avec la valeur de tagName. N'utilisez pas le nom qualifié (comme "html:a") avec cette méthode. Quand elle est appelée sur un document HTML, createElement() convertit tagName en minuscules avant de créer l'élément. Dans Firefox, Opera et Chrome, createElement(null) fonctionne comme createElement("null").
options

Un objet ElementCreationOptions facultatif contenant une seule propriété nommée  is dont la valeur est le nom de balise d'un élément personnalisé précédemment défini avec customElements.define().  Voir Web component example pour plus de détails.

Valeur de retour

L’objet Element créé.

Exemples

Exemple de base

Ici est créé un nouveau <div> qui est inséré avant l'élément avec l'identifiant "div1" .

HTML

<!DOCTYPE html>
<html>
<head>
  <title>||Travailler avec des éléments||</title>
</head>
<body>
  <div id="div1">Le texte créé dynamiquement ci-dessus.</div>
</body>
</html>

JavaScript

document.body.onload = addElement;

function addElement () { 
  // crée un nouvel élément div 
  var newDiv = document.createElement("div"); 
  // et lui donne un peu de contenu 
  var newContent = document.createTextNode("Hi there and greetings!"); 
  // ajoute le noeud texte au nouveau div créé
  newDiv.appendChild(newContent);  

  // ajoute le nouvel élément créé et son contenu dans le DOM 
  var currentDiv = document.getElementById("div1"); 
  document.body.insertBefore(newDiv, currentDiv); 
}

Exemple de composant web

L'exemple de fragment suivant est extrait de notre exemple expanding-list-web-component (voir aussi en direct). Dans ce cas, notre élément personnalisé étend la  HTMLUListElement qui représente l'élément  <ul>.

// Crée une classe pour l'élément
class ExpandingList extends HTMLUListElement {
  constructor() {
    // Toujours appeler "super" en premier dans le constructeur
    super();

    // définition du constructeur à gauche pour la brièveté
    ...
  }
}

// Définit le nouvel élément
customElements.define('expanding-list', ExpandingList, { extends: "ul" });

Si nous cherchons à créer une instance de cet élément par programmation, nous devons utiliser un appel tel que montré dans la ligne suivante :

let expandingList = document.createElement('ul', { is : 'expanding-list' })

Le nouvel élément donnera un attribut  is  dont la valeur est la balise  de nom de l'élément personnalisé.

Note : Pour la rétrocompatibilité avec les versions précédentes de la  spécification des éléments personnalisés, quelques navigateurs permettent de passer une chaîne de caractères ici, à la place d'un objet, dont la valeur est la balise de nom de l'élément personnalisé.

Spécification

Spécification Statut Commentaire
DOM
La définition de 'Document.createElement' dans cette spécification.
Standard évolutif  

Compatibilité des navigateurs

Nous convertissons les données de compatibilité dans un format JSON. Ce tableau de compatibilité utilise encore l'ancien format car nous n'avons pas encore converti les données qu'il contient. Vous pouvez nous aider en contribuant !

     
Fonctionnalité Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support (Oui) (Oui) (Oui)[1][2] (Oui) (Oui) (Oui)
options argument (Oui)[3] ? 50 (50)[4][5] ? ? ?
  
Fonctionnalité Android Android Webview Edge Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile Chrome for Android
Basic support (Oui) (Oui) (Oui) (Oui) (Oui) (Oui) (Oui) (Oui)
options argument (Oui) (Oui)[3] ? ? ? ? ? (Oui)[3]

[1] Depuis Gecko 22.0 (Firefox 22.0 / Thunderbird 22.0 / SeaMonkey 2.19) createElement() n'utilise plus l'interface HTMLSpanElement quand l'argument est "bgsounds", "multicol" ou "image".  À la place, sont utilisés : HTMLUnknownElement pour "bgsound" et "multicol", et HTMLElement pour "image".

[2] L'implémentation Gecko de createElement n'est pas conforme à la spécification DOM pour XUL et les documents XHTML : localName et namespaceURI ne sont pas définis à null sur l'élément créé. Voir bug 280692 pour plus de détails.

[3] Dans les versions précédentes de la spécification, cet argument était juste une chaîne de caractères (string) dont la valeur était la balise de nom de l'élément personnalisé. Par exemple, il pouvait prendre document.createElement("button", "custom-button") plutôt que document.createElement("button", {is: "custom-button"}). Par souci de compatibilité ascendante, Chrome accepte les deux formules, bien que la forme de chaîne soit obsolète.

[4] Voir [3] ci-dessus : comme Chrome, Firefox accepte une chaîne de caractères à la place d'un objet ici, mais seulement depuis la version 51. En version 50,  options doit être un objet.

[5] Pour expérimenter avec des éléments personnalisés dans Firefox, vous devez définir les préférences dom.webcomponents.enabled et dom.webcomponents.customelements.enabled à true (vrai).

Notes CSS Quantum

  • Dans Gecko, quand vous voulez créer un sous-arbre détaché (par exemple, un <div> créé avec createElement() qui n'est pas encore inséré dans le DOM), l'élément racine du sous-arbre est défini comme un élément de niveau bloc. Dans le nouveau moteur CSS parallèle de Firefox (aussi connu comme Quantum CSS ou Stylo, prévu pour être publié dans Firefox 57), il est défini comme "inline", (bug 1374994) selon la spécification .

Voir aussi

 

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : loella16, VictorLequin, Ealhad, Misty418, fscholz, teoli, jsx, Mgjbot, BenoitL, Takenbot
 Dernière mise à jour par : loella16,