Not reviewed yet: this page may be outdated or inconsistent with the other guides. The API reference is generated from the current source.

Web Components (Custom Elements)

Custom elements work in Reagent like any other HTML element: use the element name as the Hiccup tag keyword. Nothing needs to be registered on the Reagent side, Reagent passes the tag name to React as a string and the browser handles the rest.

[:my-element {:class "fancy"} "Hello"]

Reagent treats every tag that contains a - as a custom element (custom element names must contain a hyphen). Props for custom elements are converted slightly differently from props for built-in elements, and React 19 decides whether each prop is set as an attribute, a property or an event listener. The sections below describe how.

The property and event handling described below requires React 19. React 18 sets all custom element props as attributes and doesn't add listeners for custom events.

:class, :id and the tag shorthand

:class works the same as with other elements, including the .class and #id tag shorthand and collections (see Using Hiccup to Describe HTML). The prop is passed to React as class (not className), which React sets as the class attribute:

[:my-element.a {:class ["b" "c"]}]
;; => <my-element class="a b c"></my-element>

Prop names

Keyword prop names are converted from kebab-case to camelCase, like with other elements, except for data- and aria- props. String keys are passed as is:

[:my-element {:my-attr "a"
              "my-attr" "b"
              :data-foo-bar "c"}]
;; => <my-element myAttr="a" my-attr="b" data-foo-bar="c"></my-element>

HTML attribute names are case-insensitive, so in the browser myAttr becomes the attribute myattr. Use a string key for dashed attribute names, like "my-attr" above.

Attributes vs. properties (React 19)

For each prop that isn't an event handler, React 19 checks if the element has a property with that name (name in element):

  • If it does, the value is set as a JS property. This is how you pass non-string data, like arrays and objects, to a web component.
  • Otherwise the value is set as an attribute. true sets an empty attribute, false leaves it out.
[:my-list {:items ["a" "b"] ;; element has `items` property => el.items = ["a", "b"]
           :compact true}]  ;; no such property => attribute compact=""

Prop values are converted to JS like for other elements: vectors to arrays, maps to objects, keywords to strings. A JS value (e.g. #js {...}) is passed as is.

The property check only works if the custom element is already defined (customElements.define) when React creates the DOM element. If the element is defined later, all props are set as attributes.

Events

Prop names that are known React events, like :on-click, work as usual and receive React synthetic events.

For other props whose name starts with on and whose value is a function, React 19 adds an event listener (addEventListener) for the event named by the rest of the prop name, case-sensitively. The handler receives the native event, e.g. a CustomEvent with .-detail.

Most custom events use lowercase or dashed names, so use a string key:

[:my-element {"onmy-event" (fn [e] (js/console.log (.-detail e)))}]
;; listens to "my-event"

A keyword like :on-my-event is first converted to onMyEvent, which listens to the event MyEvent, not my-event.

Server-side rendering

When rendering to a string, props are rendered as attributes with the same name conversion as above, so :my-attr renders as myAttr="...". Use string keys when the attribute name matters.

Rendering Reagent inside a custom element

Reagent components can also be used to implement custom elements, by creating a React root inside the element (e.g. in its shadow root) and rendering into it with reagent.dom.client/render. See the shadow-dom-input example.