Skip to content
Tutorials Center
My learning

Topics

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.

JSX
import { renderToString } from 'react-dom/server';

const html = renderToString(<App />);

Try it

Components to a string

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.

A component that suspends

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

JSX
const html = renderToString(reactNode, options?);
TypeScript
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, not createRoot, 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 prerender API.
  • Escaping is automatic for text and attribute values. dangerouslySetInnerHTML is inserted as is, so sanitize it.
  • useId is 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/server picks the right build for Node, Deno, Bun or the browser through package conditions. The Node build also offers renderToPipeableStream; the browser build does not.