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.
import { createElement } from 'react'; const el = createElement('h1', { className: 'title' }, 'Hello');
Try it
Syntax
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 variableItem. WithcreateElementyou 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
cloneElementto make a modified copy. - JSX is preferred for readability. Use
createElementfor generated trees, wrappers that choose a tag name, or build-free demos. - Check what you have with
isValidElement. - Version note: React 19 stores
refinprops(see ref as a prop);keyis still kept outsideprops.
Related
- cloneElement, isValidElement, Children
- Lessons: JSX basics, JSX in depth