Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Top-Level React APIs

React createElement() function

Reference for React.createElement: the function JSX compiles to, with type, props and children arguments, key handling, dynamic types and examples.

createElement creates a React element: a plain object that describes what should appear on screen. The type can be a tag name such as 'div', a component function, or a special type like Fragment. The element is only a description. React turns it into DOM during rendering.

JSX is syntax sugar for this function: <h1 className="t">Hi</h1> becomes createElement('h1', { className: 't' }, 'Hi') in the classic transform. Modern toolchains compile JSX to jsx() calls from the react/jsx-runtime module instead, which behave the same. You rarely write createElement yourself, but it is handy for dynamic element types and in code without a build step.

JSX
import { createElement } from 'react';

const el = createElement('h1', { className: 'title' }, 'Hello');

Try it

JSX and createElement side by side
Choosing the type at run time

Syntax

TypeScript
function createElement(
  type: string | ComponentType | symbol,
  props?: object | null,
  ...children: ReactNode[]
): ReactElement;
Name Description
type A tag name string (lowercase for DOM), a component function or class, or a special type such as Fragment, Suspense or StrictMode.
props An object of props, or null if there are none. The special props key and ref are taken out of it.
...children Zero or more children: strings, numbers, elements, arrays, null. They become props.children.

Returns: an element object with type, props and key (plus internal fields). Treat it as immutable.

Children rules: with one child, props.children is that child; with several, it is an array; with none, it is undefined. If you pass children in props and also as arguments, the arguments win.

Usage notes

  • Capitalization matters in JSX, not here. In JSX, <item /> is the DOM tag 'item', while <Item /> is the variable Item. With createElement you pass the string or the variable explicitly.
  • Arrays of children need keys. Children passed as separate arguments do not need keys. An array (such as the result of .map) does, as in the second example.
  • Same element, same result. Creating an element does not render anything and has no side effects; it is cheap. Rendering happens only when React processes it.
  • Do not mutate elements. Use cloneElement to make a modified copy.
  • JSX is preferred for readability. Use createElement for generated trees, wrappers that choose a tag name, or build-free demos.
  • Check what you have with isValidElement.
  • Version note: React 19 stores ref in props (see ref as a prop); key is still kept outside props.