Custom components

A document can reference custom nodes by a kebab-case type. Register a React component for each one through the components prop:

import { Joy, type JoyComponentProps } from "@joy-dom/react";
import type { Spec } from "@joy-dom/core";

function ContactButton({ children, className, id }: JoyComponentProps) {
  return (
    <button id={id} className={className}>
      {children}
    </button>
  );
}

export function Card({ spec }: { spec: Spec }) {
  return <Joy spec={spec} components={{ "contact-button": ContactButton }} />;
}

The component receives the resolved children, className, id, and the original node. A custom node with no matching registration throws at render time.

Styling a custom node

The renderer does not pass custom components an inline style. That prop stays undefined for custom types. Style the node from the document cascade instead:

• Give the node a className.
• Write the rule in the spec's style, the same way you would for a built-in.

The renderer passes the className through, and the matching rule applies inside the shadow root.

{
  "type": "contact-button",
  "props": { "id": "primary", "className": ["btn"] }
}

alt and src follow the same rule: they stay img-only and never reach a custom component. The on* handlers are passed when the node carries a matching action. Attach them to the element that should fire (an inner <input>, a click surface), or ignore them. For anything else, read node.props directly. See §7.1 Component props.

Where next

• Interactive widgets builds a feedback card from custom components that hold host state.
• Events and actions covers the declarative bindings built-in nodes carry.