createElement

const element = createElement(type, props, ...children)

• Référence
  • createElement(type, props, ...children)
• Utilisation
  • Créer un élément sans JSX

Référence

createElement(type, props, ...children)

Appelez createElement pour créer un élément React avec un type, des props et des children.

import { createElement } from 'react';

function Greeting({ name }) {
  return createElement(
    'h1',
    { className: 'greeting' },
    'Bonjour'
  );
}

Voir d’autres exemples ci-dessous.

Paramètres

• type : l’argument type doit être un type de composant React valide. Par exemple, ce pourrait être un nom de balise (tel que 'div' ou 'span') ou un composant React (une fonction, une classe ou un composant spécial comme un Fragment).

• props : l’argument props doit être soit un objet, soit null. Si vous passez null, il sera traité comme un objet vide. React créera l’élément avec des props correspondant aux props que vous avez passées. Remarquez que les propriétés ref et key de votre objet props sont spéciales et ne seront pas disponibles en tant que element.props.ref et element.props.key sur l’element renvoyé. Elles seront exposées en tant que element.ref et element.key.

• ...children optionnels : une série quelconque de nœuds enfants. Il peut s’agir de n’importe quels nœuds React, y compris des éléments React, des chaînes de caractères, des nombres, des portails, des nœuds vides (null, undefined, true et false), et des tableaux de nœuds React.

Valeur renvoyée

createElement renvoie un objet élément React avec quelques propriétés :

• type : le type que vous avez passé.
• props : les props que vous avez passées, sauf ref et key. Si le type est un composant doté de la propriété historique type.defaultProps, alors toute prop manquante ou undefined dans props prendra sa valeur depuis type.defaultProps.
• ref : la ref que vous avez passée. Considérée null si manquante.
• key : la key que vous avez passée, convertie en chaîne de caractères. Considérée null si manquante.

En général, vous renverrez l’élément depuis votre composant, ou en ferez l’enfant d’un autre élément. Même si vous pourriez lire les propriétés de l’élément, il vaut mieux traiter tout objet élément comme une boîte noire après sa création, et vous contenter de l’afficher.

Limitations

• Vous devez traiter les éléments React et leurs props comme immuables et ne jamais changer leur contenu après création. En développement, React gèlera l’élément renvoyé, ainsi que sa propriété props (à un niveau de profondeur), pour garantir cet aspect.

• Quand vous utilisez JSX, vous devez faire démarrer le nom de la balise par une lettre majuscule afin d’afficher votre propre composant. En d’autres termes, <Something /> est équivalent à createElement(Something), mais <something /> (minuscules) est équivalent à createElement('something') (remarquez qu’il s’agit ici d’une chaîne de caractères, qui sera donc traitée comme une balise HTML native).

• Vous ne devriez passer les enfants comme arguments multiples à createElement que s’ils sont statiquement connus, comme par exemple createElement('h1', {}, child1, child2, child3). Si vos enfants sont dynamiques, passez leur tableau entier comme troisième argument : createElement('ul', {}, listItems). Ça garantit que React vous avertira en cas de key manquantes lors de listes dynamiques. C’est inutile pour les listes statiques puisque leur ordre et leur taille ne changent jamais.

Utilisation

Créer un élément sans JSX

Si vous n’aimez pas JSX ou ne pouvez pas l’utiliser dans votre projet, vous pouvez utiliser createElement comme alternative.

Pour créer un élément sans JSX, appelez createElement avec un type, des props et des enfants :

import { createElement } from 'react';

function Greeting({ name }) {
  return createElement(
    'h1',
    { className: 'greeting' },
    'Bonjour ',
    createElement('i', null, name),
    '. Bienvenue !'
  );
}

Les enfants sont optionnels, et vous pouvez en passer autant que vous le souhaitez (l’exemple ci-dessus a trois enfants). Ce code affichera un en-tête <h1> avec un message de bienvenue. À titre de comparaison, voici le même exemple utilisant JSX :

function Greeting({ name }) {
  return (
    <h1 className="greeting">
      Bonjour <i>{name}</i>. Bienvenue !
    </h1>
  );
}

Pour afficher votre propre composant React, passez une fonction telle que Greeting comme type, plutôt qu’une chaîne de caractères comme 'h1' :

export default function App() {
  return createElement(Greeting, { name: 'Clara' });
}

En JSX, ça donnerait ceci :

export default function App() {
  return <Greeting name="Clara" />;
}

Voici un exemple complet écrit avec createElement :

Et voici le même écrit en JSX :

Les deux styles sont acceptables, vous pouvez donc utiliser celui que vous préférez dans votre projet. L’avantage principal de JSX, comparé à createElement, c’est qu’il est plus facile de voir où les éléments commencent et où ils finissent.

// Légèrement simplifié
{
  type: Greeting,
  props: {
    name: 'Clara'
  },
  key: null,
  ref: null,
}