Inject a child prop
A wrapper component needs to add or override a prop on a single supplied child while retaining the child's type and other props.
React 19+ · Function
cloneElement
Creates a new React element from an existing valid element, selectively overriding its props, key, ref, or children. The original element remains unchanged.
How it works
cloneElement creates a new React element from an existing valid element. It shallowly combines the original props with supplied overrides, preserves the original children when no child arguments are provided, and can replace the key or ref.
Syntax
cloneElement(element, props, ...children)Parameters
| Name | Type | Description |
|---|---|---|
element | React element | A valid React element, such as JSX, a createElement result, or another cloneElement result. |
props | object | null | An object of overriding props, or null to retain the source props. |
...children | ReactNode | Optional React child nodes. If omitted, the source element's children are preserved. |
Returns
A new React element object with the source type, shallowly merged props, and original key/ref unless overridden.
Key points
- It derives a fresh React element from an existing one rather than changing that existing object.
- The source must be a valid React element, such as JSX or an element returned by createElement.
- Use null to retain all original props, or provide an object containing selective overrides.
- Provided props win individually; unspecified props continue to come from the original element.
- The variadic children can contain React elements, text, numbers, portals, empty nodes, or arrays of React nodes.
- Nested prop structures are not recursively merged; replacement values must be assembled by the caller.
Common mistakes
- The operation returns a separate element; it does not mutate the source element.
- Passing even an empty or explicit children argument changes the children behavior, so omit the variadic argument when preserving them.
- Overriding key or ref changes element identity or ref ownership and should be deliberate.
Example: Override a child prop
import { cloneElement, type ReactElement } from 'react';
type ButtonProps = { children: React.ReactNode; className?: string };
function Emphasize({ child }: { child: ReactElement<ButtonProps> }) {
return cloneElement(child, {
className: `${child.props.className ?? ''} emphasized`.trim(),
});
}
export default function App() {
return <Emphasize child={<button className="primary">Save</button>} />;
}The wrapper creates a new button element while preserving its existing props and replacing only the className.
When to use it
Transform children
A component needs to replace or augment an element's children while retaining its element type and selected original props.
Deliberately replace identity metadata
A controlled composition pattern requires explicitly changing an element's key or ref at the cloning boundary.
Interview questions
QWhat does cloneElement do?
It accepts a valid React element, an object or null for props, and optional child nodes. The returned element uses the supplied prop values over the original ones and otherwise retains the original props.
Follow-up: What happens to children when none are supplied? The original element.props.children is retained; supplying child arguments replaces them.
QHow are props and element identity handled?
It returns a new React element object with the same type by default. Its props are produced by shallowly merging the source props with the overriding props.
Follow-up: Does it deep-merge nested props? No. The documented merge is shallow, so nested objects require an explicitly constructed replacement value.
QWhat constraints and design concerns apply?
A valid React element can be a JSX node, the result of createElement, or the result of another cloneElement call. The source element itself is not modified.
Follow-up: When might cloneElement be a poor design choice? When it obscures data flow; explicit component props, context, or a render prop can often communicate ownership more clearly.
Related
createElementisValidElementChildrencreateContext