React

@joy-dom/react renders a Joy DOM JSON document into React elements. It powers the live previews you see on the spec page.

Install

bun add @joy-dom/react @joy-dom/spec

@joy-dom/spec is a peer dependency. It exports the JSON Schema and TypeScript types.

First render

import { JoyDom } from "@joy-dom/react";
import type { Spec } from "@joy-dom/spec";

const spec: Spec = {
  version: 1,
  style: {
    ".hello": { display: "flex", padding: { value: 16, unit: "px" } },
    p: { display: "flex" },
  },
  breakpoints: [],
  layout: {
    type: "div",
    props: { className: ["hello"] },
    children: [{ type: "p", children: ["Hello Joy DOM"] }],
  },
};

export function App() {
  return <JoyDom spec={spec} />;
}

Drop <JoyDom> anywhere you'd put a regular React component.

Custom components

If the document references custom nodes (kebab-case type), pass them via the components prop:

import { JoyDom, type JoyDomComponentProps } from "@joy-dom/react";
import type { Spec } from "@joy-dom/spec";

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

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

The component receives the resolved children, className, style, id, and the original node. See §7.1 Component props.

Missing a registration for a custom node throws at render time.

Events and actions

A node binds an event to a named action in its props (see §8 Events and actions). Pass an actions map keyed by action name; each handler receives the DOM event and the binding's params:

import { JoyDom, type ActionHandler } from "@joy-dom/react";
import type { Spec } from "@joy-dom/spec";

const spec: Spec = {
  version: 1,
  style: { ".buy": { display: "flex" } },
  breakpoints: [],
  layout: {
    type: "div",
    props: {
      className: ["buy"],
      onclick: { type: "action", action: "checkout", params: { sku: "joy-01" } },
    },
    children: ["Buy now"],
  },
};

const checkout: ActionHandler = ({ event, params }) => {
  event.preventDefault();
  console.log("checkout", params?.sku);
};

export function Store() {
  return <JoyDom spec={spec} actions={{ checkout }} />;
}

A binding that names an action absent from the map throws at render, so a typo surfaces immediately. Pass missingAction="ignore" to leave such events unbound and render the rest of the tree.

The renderer wires bindings on built-in nodes only. A custom component receives the raw node, so it reads any bindings from node.props and decides how to use them. The interactive widgets use case walks through a card that mixes both.

Load documents at runtime

When the document isn't part of your build:

import { useEffect, useState } from "react";
import { JoyDom } from "@joy-dom/react";
import { SpecSchema, type Spec } from "@joy-dom/spec";

export function Card({ url }: { url: string }) {
  const [spec, setSpec] = useState<Spec | null>(null);

  useEffect(() => {
    fetch(url)
      .then((response) => response.json())
      .then((data) => SpecSchema.parse(data))
      .then(setSpec);
  }, [url]);

  if (!spec) return null;
  return <JoyDom spec={spec} />;
}

Calling SpecSchema.parse at the boundary makes malformed documents fail fast with a readable Zod error.

Server-side rendering

<JoyDom> renders into its own shadow root. On the server that's a declarative shadow root (<template shadowrootmode>); the browser attaches it while parsing the HTML, which means React can't hydrate that subtree afterwards. So pick one:

Common integration patterns

API reference

<JoyDom> (component)

The primary entry point. Renders a Joy DOM document as React elements.

<JoyDom spec={spec} components={{ "contact-button": ContactButton }} />

Props (JoyDomProps)

<JoyDom> renders into its own shadow root, so the document's global ids and classes stay isolated from the host page.

Rendering to a string

For non-component contexts — a server function, a test — render with react-dom/server:

const html = renderToStaticMarkup(<JoyDom spec={spec} />);

The markup contains a declarative shadow root (<template shadowrootmode>); mount it with element.setHTMLUnsafe(html) so the browser attaches the shadow.

Types

JoyDomProps

type JoyDomProps = JoyDomRenderOptions & {
  spec: Spec;
  /** Ref to the rendered content element inside the shadow root. */
  ref?: Ref<HTMLDivElement>;
};

JoyDomRenderOptions

The options <JoyDom> accepts alongside spec:

type JoyDomRenderOptions = {
  components?: Record<string, JoyDomComponent>;
  actions?: Record<string, ActionHandler>;
  missingAction?: "ignore" | "throw";
  responsive?: "media" | "container";
};

JoyDomComponent<N>

A custom component:

type JoyDomComponent<N extends Node = Node> = ComponentType<JoyDomComponentProps<N>>;

JoyDomComponentProps<N>

What custom components receive:

type JoyDomComponentProps<N extends Node = Node> = {
  children?: ReactNode;
  node: N;
  alt?: string;
  id?: string;
  className?: string;
  src?: string;
  style?: CSSProperties;
};

RenderedNodeProps

The bag of props the renderer passes to every node (text, image, block, or custom):

type RenderedNodeProps = {
  alt?: string;
  id?: string;
  className?: string;
  src?: string;
  style?: CSSProperties;
};

Error behavior

• A document fails SpecSchema validation at the boundary you control. @joy-dom/react does not call SpecSchema.parse itself, so validate before passing.
• A document references a custom node with no entry in components. The renderer throws. This is intentional. Silent fallback hides the real bug.
• Style values that don't map to a CSS property are ignored. The Zod schema would have caught these if you validated upstream.

Where next

• Tutorial, a guided walk through building a document.
• Custom components, the tutorial chapter on writing them.
• @joy-dom/spec, the types this renderer consumes.
• Specification, the supported nodes, properties, and breakpoints.