React Reference ยท react-dom/server and Static APIs
React renderToString function
Reference for react-dom/server renderToString: turn a React tree into an HTML string for hydration, with its options, escaping rules and Suspense limits.
renderToString renders a React tree to an HTML string, synchronously. You send that string to the browser, and hydrateRoot later attaches React to it. It is the simplest server rendering function: one call, one string, no streams.
It does not wait for data. Components that suspend are not awaited, and the nearest Suspense fallback is written instead. Effects and event handlers do not run on the server, and the output carries small comment markers that hydration needs. For streaming or for waiting on data, use renderToPipeableStream or renderToReadableStream instead; React recommends those over renderToString for new code.
import { renderToString } from 'react-dom/server'; const html = renderToString(<App />);
Try it
The string has <!-- --> between the label, the colon and the number, because they are separate text nodes. Text is escaped, and the onClick handler is simply absent.
The result contains the fallback and the marker <!--$!-->, which tells the client to render that part itself. The promise is not awaited. The <template> holds a development message and is shortened here.
Syntax
const html = renderToString(reactNode, options?);
function renderToString( children: ReactNode, options?: { identifierPrefix?: string } ): string;
| Name | Description |
|---|---|
reactNode |
The tree to render, usually a root component such as <App />. |
options.identifierPrefix |
A string prepended to the IDs made by useId. Use a different prefix for each React root on the page so IDs cannot collide. |
Returns: an HTML string. It does not include <!DOCTYPE html>; add it yourself when you render a full <html> tree.
Errors: an error thrown outside a Suspense boundary makes the call throw. An error inside a boundary does not throw: React writes the fallback and the client retries the render.
Usage notes
- Hydrate it with
hydrateRoot, notcreateRoot, and render the same tree with the same props on the client. A difference causes a hydration mismatch. - It is synchronous and blocking. The whole page must finish before you send the first byte. Streaming APIs avoid that.
- No data waiting. A component that suspends yields its fallback and a client-render marker. Fetch data before calling it, or switch to a streaming or
prerenderAPI. - Escaping is automatic for text and attribute values.
dangerouslySetInnerHTMLis inserted as is, so sanitize it. useIdis safe: the server and the client agree on the IDs, provided the tree and the prefix match.- Effects, refs and layout effects do not run. Browser-only code belongs in effects, or behind a check that treats the server and first client render the same way.
- For output you will not hydrate, use
renderToStaticMarkup, which leaves out the markers. - Import path:
react-dom/serverpicks the right build for Node, Deno, Bun or the browser through package conditions. The Node build also offersrenderToPipeableStream; the browser build does not.