renderToMarkup -> renderToHTML

2026-02-25 23:05:23 +00:00 · 2024-08-14 09:27:27 +02:00
parent c0bd72d2c7
commit be631ebd80
3 changed files with 21 additions and 15 deletions
--- a/src/content/reference/react-markup/renderToHTML.md
+++ b/src/content/reference/react-markup/renderToHTML.md
@@ -0,0 +1,74 @@
+---
+title: renderToHTML
+canary: true
+---
+
+
+<Intro>
+
+`renderToHTML` renders a React tree to non-interactive HTML.
+
+```js
+const stream = renderToHTML(reactNode, options?)
+```
+
+</Intro>
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `renderToHTML(reactNode, options?)` {/*rendertohtml*/}
+
+You can call `renderToHTML` to render a non-interactive tree of React components to HTML.
+By default, it supports shared components and built-in components.
+Server Components are only allowed if used in a React Server environment (e.g. in Server Actions).
+You can also use it during Client-Side Rendering but only without Server Components.
+
+When a `<html>` tag is rendered, `renderToHTML` will automatically add `<!DOCTYPE html>` doctype.
+
+```js
+import { experimental_renderToHTML as renderToHTML } from 'react-dom/server';
+
+const markup = await renderToHTML(<App />);
+```
+
+#### Parameters {/*parameters*/}
+
+* `reactNode`: A React node you want to render to HTML. For example, a JSX element like `<App />`.
+
+* **optional** `options`: An object for server render.
+  * **optional** `identifierPrefix`: A string prefix React uses for IDs generated by [`useId`.](/reference/react/useId) Useful to avoid conflicts when the markup is embedded in or combined with other markup that is rendered by React.  
+  * **optional** `onError`: A callback that fires whenever there is a server error. By default, this only calls `console.error`. If you override it to [log crash reports,](#logging-crashes-on-the-server) make sure that you still call `console.error`. This is different to the rejection reason of the created Promise since it'll include the parent component stack.
+  * **optional** `signal`: An [abort signal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that lets you [abort rendering](#aborting-server-rendering). The original Promise will reject.
+
+#### Returns {/*returns*/}
+
+`renderToHTML` returns a Promise that will resolve with the HTML string of the rendered React tree.
+
+#### Caveats {/*caveats*/}
+
+* Will throw when Client APIs (e.g. `useState` or `useEffect`) are used.
+
+---
+
+## Usage {/*usage*/}
+
+### Rendering a React tree as an Email {/*rendering-a-react-tree-as-an-email*/}
+
+Await the call of `renderToHTML` :
+
+```js {7}
+import { experimental_renderToHTML as renderToHTML } from 'react-markup';
+import EmailTemplate from './my-email-template-component.js'
+
+async function action(email, name) {
+  "use server";
+  // ... in your server, e.g. a Server Action...
+  const htmlString = await renderToHTML(<EmailTemplate name={name} />);
+  // ... send e-mail using some e-mail provider
+  await sendEmail({ to: email, contentType: 'text/html', body: htmlString });
+}
+```