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.
import { renderToStaticMarkup } from 'react-dom/server'; const html = renderToStaticMarkup(<Receipt order={order} />);
Try it
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 &.
Syntax
const html = renderToStaticMarkup(reactNode, options?);
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.
hydrateRootexpects the markersrenderToStringwrites. Without them React reports a mismatch and rebuilds the DOM. - Event handlers are dropped.
onClickand 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;dangerouslySetInnerHTMLis not. - Email clients need inline styles. Many ignore
<style>blocks, so use thestyleprop. Class names only help if your pipeline inlines a stylesheet. - Uncontrolled initial values become plain attributes:
defaultValuebecomesvalue,defaultCheckedbecomeschecked, and a<select>marks the matching<option>asselected. - 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.
Related
- renderToString, prerender, hydrateRoot
- Lessons: SSR and hydration, JSX basics