Skip to content
Tutorials Center
My learning

Topics

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.

JSX
<rating-badge value={4} label="Quality" onrate={(event) => console.log(event.detail)} />

Try it

Properties versus attributes
Listening to a custom event

Syntax

JSX
<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 with customElements.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. onMyEvent listens for MyEvent, 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.
  • className follows the same rule. On an ordinary custom element it becomes the class attribute. If your element class defines its own className property, 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.IntrinsicElements extension to get type checking.