React Reference ยท Built-in DOM Components
Custom elements (web components) in React
Reference for using custom elements (web components) in React 19: how props become properties or attributes, how events are wired, and common pitfalls.
A custom element is any tag whose name contains a hyphen, such as <rating-badge> or <my-tabs>, that the browser upgrades with a JavaScript class registered through customElements.define(). You use it in JSX like any other tag. React renders the element and passes your props to it, but it does not know what the element does internally.
React 19 added full support for custom elements. For each prop, React checks whether the element already has a property of that name. If it does, React assigns the property (so objects, arrays and numbers arrive with their real types). If it does not, React sets an attribute with a string value. Props that start with on are treated as event listeners.
<rating-badge value={4} label="Quality" onrate={(event) => console.log(event.detail)} />
Try it
Syntax
<tag-name attribute="text" property={anyValue} onevent-name={handler} />
| Name | Description |
|---|---|
| Attribute-style props | Strings, numbers and booleans for names the element does not define as properties. They end up as HTML attributes. |
| Property-style props | Any value, including objects, arrays and functions, when the element has a property with that name (prop in element). React assigns it directly. |
on... props |
Event listeners. The text after on is used as the exact event name, so onping listens for ping and onitem-selected listens for item-selected. Add Capture to the end for the capture phase. |
className, style, ref, children |
Work as on built-in elements. |
Returns: a normal element in the DOM. The custom element's own class decides what it renders.
Edge cases: a prop of true becomes an empty attribute and false leaves the attribute out. null and undefined also leave it out.
Usage notes
- Register before first use. Call
customElements.define()once, at module level, and guard withcustomElements.get(name)if the file can be evaluated more than once (hot reload, repeated TryIt runs). - Event names are exact. React does not lowercase or translate them.
onMyEventlistens forMyEvent, which is almost never what the element dispatches. Use the same spelling as the element's documentation. Events that do not bubble still reach the listener because React attaches it to the element itself. classNamefollows the same rule. On an ordinary custom element it becomes theclassattribute. If your element class defines its ownclassNameproperty, React assigns that property instead, so avoid defining one.- Children are light DOM. JSX children become light DOM children, which a shadow root can show through
<slot>. React cannot reach inside a closed or open shadow tree. - Do not let the element and React both manage the same nodes. If the element rewrites its own children (as the examples do with
innerHTML), do not also pass JSX children to it. - Server rendering. Without a rendered shadow tree on the server, the element shows only its light DOM until it upgrades. Plan for that first paint.
- Older React versions. React 18 and earlier set everything as attributes and had no
on...event props for custom events, so wrapper components were needed. React 19 removes that requirement. - TypeScript. Declare custom tags in a global
JSX.IntrinsicElementsextension to get type checking.