document.createElement
======================

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
-------


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

### Paramètres

tagName

Une chaîne de caractères (`DOMString`) 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")`.

optionsFacultatif

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 Exemple de composant web 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


```html
<!doctype html>
<html>
  <head>
    <title>||Working with elements||</title>
  </head>
  <body>
    <div id="div1">The text above has been created dynamically.</div>
  </body>
</html>
```


#### JavaScript


```js
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 nœud 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` (en-US) qui représente l'élément `<ul>`.


```js
// 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 omise 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 :


```js
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écifications
--------------

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-createelement① |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Node.removeChild()`
* `Node.replaceChild()`
* `Node.appendChild()`
* `Node.insertBefore()`
* `Node.hasChildNodes()`
* `document.createElementNS()` — pour spécifier explicitement l'URI de l'espace de noms de l'élément.