Server rendering

<Joy> renders into its own shadow root. On the server that is a declarative shadow root (<template shadowrootmode>). The browser attaches it while parsing the HTML, which means React cannot hydrate that subtree afterwards. Two approaches work around this.

Static or string rendering

renderToStaticMarkup(<Joy spec={spec} />) produces the declarative shadow root. Mount it with element.setHTMLUnsafe(html) so the browser attaches it. No hydration is involved, which suits static generation or a server function that returns markup.

Inside a hydrated app

For Next.js, Waku, or Remix, render <Joy> on the client so its shadow root attaches client-side rather than hydrating. Gate it on a mounted flag:

const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
return mounted ? <Joy spec={spec} /> : null;

Joy DOM's own website does exactly this for its previews.

Rendering to a string

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

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

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

Load documents at runtime

When the document is not part of your build, fetch it and validate at the boundary:

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

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 <Joy spec={spec} />;
}

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

Integration patterns