renderToString

renderToString synchronously renders a React tree to an HTML string. This is a legacy API that does not support Suspense or streaming.

const html = renderToString(element, options?);

renderToString does not support Suspense and cannot stream output. For new projects, use renderToPipeableStream (Node.js) or renderToReadableStream (Web Streams) instead.

Reference

`renderToString(element, options?)`

Renders a React element to an HTML string with React-specific attributes like data-reactroot.

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

const html = renderToString(<App />);

Parameters

element: ReactNode - The React element to render
options: Object (optional)
- identifierPrefix: string - Prefix for IDs generated by useId. Useful for avoiding conflicts when using multiple roots on the same page.

Returns

Returns a string containing the rendered HTML with React attributes.

Caveats

No Suspense support: If a component suspends, renderToString will throw an error
Blocking: Must wait for the entire tree to render before returning
No streaming: Cannot send HTML to client until everything is ready
Client-side: Also available in browser environments but not commonly used there

Usage

Basic server-side rendering

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

function handleRequest(req, res) {
  const html = renderToString(<App />);
  
  res.send(`
    <!DOCTYPE html>
    <html>
      <head>
        <title>My App</title>
      </head>
      <body>
        <div id="root">${html}</div>
        <script src="/bundle.js"></script>
      </body>
    </html>
  `);
}

Using with Express

Node.js
Edge Runtime

import express from 'express';
import { renderToString } from 'react-dom/server';
import App from './App';

const app = express();

app.get('/', (req, res) => {
  try {
    const html = renderToString(<App />);
    
    res.send(`
      <!DOCTYPE html>
      <html>
        <head>
          <meta charset="utf-8" />
          <title>My App</title>
          <link rel="stylesheet" href="/styles.css" />
        </head>
        <body>
          <div id="root">${html}</div>
          <script src="/bundle.js"></script>
        </body>
      </html>
    `);
  } catch (error) {
    console.error('Rendering error:', error);
    res.status(500).send('Internal Server Error');
  }
});

app.listen(3000);

import { renderToString } from 'react-dom/server.edge';
import App from './App';

export default async function handler(request) {
  try {
    const html = renderToString(<App />);
    
    return new Response(`
      <!DOCTYPE html>
      <html>
        <head>
          <meta charset="utf-8" />
          <title>My App</title>
        </head>
        <body>
          <div id="root">${html}</div>
          <script src="/bundle.js"></script>
        </body>
      </html>
    `, {
      headers: { 'Content-Type': 'text/html' }
    });
  } catch (error) {
    return new Response('Internal Server Error', { status: 500 });
  }
}

Setting identifier prefix

Use identifierPrefix to avoid ID conflicts when rendering multiple React roots on the same page:

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

function ComponentWithId() {
  const id = useId();
  return <label htmlFor={id}>Name: <input id={id} /></label>;
}

// Render multiple independent apps
const html1 = renderToString(<App1 />, {
  identifierPrefix: 'app1-'
});

const html2 = renderToString(<App2 />, {
  identifierPrefix: 'app2-'
});

// IDs won't conflict:
// app1-:r0: vs app2-:r0:

Handling errors

renderToString throws errors synchronously, so use try-catch:

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

function renderApp() {
  try {
    return renderToString(<App />);
  } catch (error) {
    console.error('Failed to render:', error);
    // Return error page HTML
    return renderToString(<ErrorPage error={error.message} />);
  }
}

Limitations

No Suspense Support

If your component tree contains a Suspense boundary with a component that suspends, renderToString will throw an error:

// This will throw an error
function App() {
  return (
    <Suspense fallback={<Loading />}>
      <AsyncComponent /> {/* If this suspends, renderToString throws */}
    </Suspense>
  );
}

renderToString(<App />); // Error!

Solution: Use renderToPipeableStream or renderToReadableStream which fully support Suspense.

Blocking Rendering

renderToString must render the entire component tree before returning:

function App() {
  // Even if this takes 5 seconds, renderToString waits
  const data = fetchDataSync(); // Blocks!
  return <div>{data}</div>;
}

// User sees nothing until ALL rendering completes
const html = renderToString(<App />);

Solution: Use streaming APIs to send HTML progressively as components become ready.

Performance Considerations

renderToString is synchronous and blocks the event loop:

app.get('/', (req, res) => {
  // This blocks the server for ALL users during rendering
  const html = renderToString(<LargeApp />); // 100ms
  res.send(html);
  
  // No other requests can be processed during these 100ms
});

Solution: Use streaming APIs which are non-blocking and allow concurrent request handling.

Migrating to Modern APIs

If you’re using renderToString, consider migrating to modern streaming APIs:

Before (renderToString)
After (renderToPipeableStream)

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

app.get('/', (req, res) => {
  const html = renderToString(<App />);
  
  res.send(`
    <!DOCTYPE html>
    <html>
      <body>
        <div id="root">${html}</div>
        <script src="/bundle.js"></script>
      </body>
    </html>
  `);
});

import { renderToPipeableStream } from 'react-dom/server';

app.get('/', (req, res) => {
  const { pipe } = renderToPipeableStream(<App />, {
    bootstrapScripts: ['/bundle.js'],
    onShellReady() {
      res.setHeader('Content-Type', 'text/html');
      pipe(res);
    },
    onError(error) {
      console.error(error);
    }
  });
});

Runtime Availability

renderToString is available in multiple runtime exports:

Node.js
Edge
Browser

import { renderToString } from 'react-dom/server';
// or
import { renderToString } from 'react-dom/server.node';

Uses ReactDOMLegacyServerNode implementation.

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

Uses ReactDOMLegacyServerBrowser implementation.

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

Available but rarely used in browser contexts.

Common Issues

Suspense error: does not support Suspense

renderToString cannot handle Suspense boundaries. Remove Suspense or migrate to renderToPipeableStream/renderToReadableStream.

// Remove this:
<Suspense fallback={<div>Loading...</div>}>
  <AsyncComponent />
</Suspense>

// Or migrate to streaming API

Hydration mismatch warnings

Ensure server and client render identical HTML. Common causes:

Using Date.now() or Math.random() during render
Different data on server vs client
Browser-specific APIs used during render

// Bad: Different on server and client
<div>{Date.now()}</div>

// Good: Use useEffect for client-only code
function Clock() {
  const [time, setTime] = useState(null);
  useEffect(() => {
    setTime(Date.now());
  }, []);
  return <div>{time || 'Loading...'}</div>;
}

Memory leaks with large renders

renderToString builds the entire HTML string in memory. For very large pages, this can cause memory issues.Solution: Use streaming APIs which write directly to the response stream without buffering.

React Core

Hooks

ReactDOM

Server APIs

renderToString

renderToString

Reference

`renderToString(element, options?)`

Parameters

Returns

Caveats

Usage

Basic server-side rendering

Using with Express

Setting identifier prefix

Handling errors

Limitations

No Suspense Support

Blocking Rendering

Performance Considerations

Migrating to Modern APIs

Runtime Availability

Common Issues

See Also

​renderToString

​Reference

​renderToString(element, options?)

​Parameters

​Returns

​Caveats

​Usage

​Basic server-side rendering

​Using with Express

​Setting identifier prefix

​Handling errors

​Limitations

​No Suspense Support

​Blocking Rendering

​Performance Considerations

​Migrating to Modern APIs

​Runtime Availability

​Common Issues

​See Also

renderToString

Reference

`renderToString(element, options?)`

Parameters

Returns

Caveats

Usage

Basic server-side rendering

Using with Express

Setting identifier prefix

Handling errors

Limitations

No Suspense Support

Blocking Rendering

Performance Considerations

Migrating to Modern APIs

Runtime Availability

Common Issues

See Also