Skip to content
Tutorials Center
My learning

Topics

React Reference ยท react-dom/server and Static APIs

React renderToStaticMarkup function

Reference for react-dom/server renderToStaticMarkup: render React to clean HTML without hydration markers, for emails, feeds and pages that never hydrate.

renderToStaticMarkup renders a React tree to an HTML string, like renderToString, but leaves out everything that exists only for hydration: the <!-- --> separators between adjacent text nodes and the Suspense comment markers. What remains is plain HTML, as if you had written it by hand.

Use it when no React code will ever run on the other side: HTML emails, RSS or Atom items, PDF templates, static pages with no JavaScript. Do not use it for a page you plan to hydrate, because the missing markers make hydration fail.

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

const html = renderToStaticMarkup(<Receipt order={order} />);

Try it

Compare the two outputs
An email body with inline styles

The second log line shows that an ordinary Suspense boundary leaves no markers either: only <div><p>ready</p></div> remains. The table is shown rendered and as source; & in the text is escaped to &amp;.

Syntax

JSX
const html = renderToStaticMarkup(reactNode, options?);
TypeScript
function renderToStaticMarkup(
  children: ReactNode,
  options?: { identifierPrefix?: string }
): string;
Name Description
reactNode The tree to render.
options.identifierPrefix Prefix for the IDs generated by useId.

Returns: an HTML string without hydration markers and without a doctype.

Errors: an error thrown outside a Suspense boundary makes the call throw.

Usage notes

  • Never hydrate its output. hydrateRoot expects the markers renderToString writes. Without them React reports a mismatch and rebuilds the DOM.
  • Event handlers are dropped. onClick and similar props produce no attributes. A static page is not interactive just because it came from React.
  • Suspense does not wait. A component that suspends is replaced by the boundary fallback, and no client-render marker is written, because nobody will pick it up. Load the data before rendering.
  • Same escaping as renderToString. Text and attribute values are escaped; dangerouslySetInnerHTML is not.
  • Email clients need inline styles. Many ignore <style> blocks, so use the style prop. Class names only help if your pipeline inlines a stylesheet.
  • Uncontrolled initial values become plain attributes: defaultValue becomes value, defaultChecked becomes checked, and a <select> marks the matching <option> as selected.
  • Good for tests. A string is easy to compare in a snapshot, though a DOM-based testing library tells you more about what users see.
  • Streams are not offered. It is synchronous. For a very large static page use prerender.