Overview

@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/react declares react and react-dom 19 as peer dependencies; install them in your app if they aren't already there. @joy-dom/spec carries the TypeScript types and JSON Schema for the document format — install it alongside so you can type your specs.

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. It renders the document into its own shadow root, so the spec's global ids and classes stay isolated from the host page.

Where next

• Custom components, for the document's kebab-case node types.
• Events and actions, wiring onclick/onfocus/onblur/onchange to handlers.
• Server rendering, the shadow-root tradeoffs and how to load documents.
• API reference, every prop and type.