createElement

createElement lets you create a React element. It serves as an alternative to writing JSX.

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

Reference

`createElement(type, props, ...children)`

Call createElement to create a React element with the given type, props, and children.

import { createElement } from 'react';

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

See more examples below.

Parameters

type: The type argument must be a valid React component type. For example, it could be a tag name string (such as 'div' or 'span'), or a React component (a function, a class, or a special component like Fragment).
props: The props argument must either be an object or null. If you pass null, it will be treated the same as an empty object. React will create an element with props matching the props you have passed. Note that ref and key from your props object are special and will not be available as element.props.ref and element.props.key on the returned element. They will be available as element.ref and element.key.
optional ...children: Zero or more child nodes. They can be any React nodes, including React elements, strings, numbers, portals, empty nodes (null, undefined, true, and false), and arrays of React nodes.

Returns

createElement returns a React element object with a few properties:

type: The type you have passed.
props: The props you have passed except for ref and key. If the type is a component with legacy type.defaultProps, then any missing or undefined props will get the values from type.defaultProps.
ref: The ref you have passed. If missing, null.
key: The key you have passed, coerced to a string. If missing, null.

Usually, you'll return the element from your component or make it a child of another element. Although you may read the element's properties, it's best to treat every element as opaque after it's created, and only render it.

Caveats

You must treat React elements and their props as immutable and never change their contents after creation. In development, React will freeze the returned element and its props property shallowly to enforce this.
When you use JSX, you must start a tag with a capital letter to render your own custom component. In other words, <Something /> is equivalent to createElement(Something), but <something /> (lowercase) is equivalent to createElement('something') (note it's a string, so it will be treated as a built-in HTML tag).
You should only pass children as multiple arguments to createElement if they are all statically known, like createElement('h1', {}, child1, child2, child3). If your children are dynamic, pass the entire array as the third argument: createElement('ul', {}, listItems). This ensures that React will warn you about missing keys for any dynamic lists. For static lists this is not necessary because they never reorder.

Usage

Creating an element without JSX

If you don't like JSX or can't use it in your project, you can use createElement as an alternative.

To create an element without JSX, call createElement with some type, 2>props, and 3>children:

import { createElement } from 'react';

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

The 3>children are optional, and you can pass as many as you need (the example above has three children). This code will display a <h1> header with a greeting. For comparison, here is the same example rewritten with JSX:

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

To render your own React component, pass a function like Greeting as the type instead of a string like 'h1':

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

With JSX, it would look like this:

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

Here is a complete example written with createElement:

import { createElement } from 'react';

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

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

.greeting {
  color: darkgreen;
  font-family: Georgia;
}

And here is the same example written using JSX:

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

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

.greeting {
  color: darkgreen;
  font-family: Georgia;
}

Both coding styles are fine, so you can use whichever one you prefer for your project. The main benefit of using JSX compared to createElement is that it's easy to see which closing tag corresponds to which opening tag.

What is a React element, exactly?

An element is a lightweight description of a piece of the user interface. For example, both <Greeting name="Taylor" /> and createElement(Greeting, { name: 'Taylor' }) produce an object like this:

// Slightly simplified
{
  type: Greeting,
  props: {
    name: 'Taylor'
  },
  key: null,
  ref: null,
}

Note that creating this object does not render the Greeting component or create any DOM elements.

A React element is more like a description--an instruction for React to later render the Greeting component. By returning this object from your App component, you tell React what to do next.

Creating elements is extremely cheap so you don't need to try to optimize or avoid it.

Reference ​

createElement(type, props, ...children) ​

Parameters ​

Returns ​

Caveats ​

Usage ​

Creating an element without JSX ​

What is a React element, exactly? ​