How to Use React 19.3ās Browser API for SSR
React 19.3 adds the browser() API for server-rendered apps. Learn how to isolate browser-only components, use Suspense correctly, and avoid unnecessary client-only rendering.
On this page
React 19.3, released on September 9, 2026, adds a new browser API for components that cannot produce meaningful HTML during server-side rendering. Instead of checking typeof window or waiting for an effect to run after hydration, you can explicitly tell React to render a component only in the browser and let a Suspense fallback handle the server output.
This is useful for web applications that read localStorage, inspect the user's time zone, use browser-only APIs, or depend on client-side data that does not exist on the server. The important detail is that browser() does not make the entire application client-only; it isolates the part that genuinely needs the browser.
What React 19.3 changes for browser-only components
Server-side rendering (SSR) produces HTML on the server before the page reaches the browser, while hydration connects that HTML to React in the browser. Previously, developers commonly handled browser-only components with a mounted state, an effect, or a typeof window !== 'undefined' check. Those techniques can work, but they make the component responsible for managing its own transition from server output to browser output.
React 19.3 introduces browser() in react-dom as a first-class way to opt a subtree out of server rendering. When React encounters use(browser()) during server rendering, the component suspends and the nearest Suspense boundary supplies its fallback. After hydration in the browser, use(browser()) resolves normally and the component can use browser APIs.
Update the project to React 19.3 first
Before using the API, make sure the application is actually running React 19.3. The stable react package is version 19.3.0, and the React team's release notes identify browser() as one of the new React DOM features in that release.
In a project managed directly with npm, update both React packages together:
npm install react@19.3.0 react-dom@19.3.0Then verify the installed versions:
npm list react react-domThe result should show version 19.3.0 for the packages you are using. If a framework controls React versions for your project, follow that framework's supported upgrade path instead of forcing a package version that it does not support.
Identify code that truly needs the browser
The new API is not a replacement for normal React rendering. Use it when a component genuinely depends on something unavailable during server rendering. Common examples include localStorage, browser time-zone detection through Intl.DateTimeFormat, media queries that must be evaluated in the browser, or browser-specific APIs exposed through window and navigator.
For example, this component cannot safely read localStorage while the server is rendering because localStorage belongs to the browser environment:
function SavedDraft() {
const draft = localStorage.getItem('draft');
return Saved draft: {draft}
;
}Putting the component behind a client-only condition can avoid the server error, but it also leaves the application to decide how the server should represent that missing content. React 19.3 gives that responsibility to the rendering model instead.
Wrap the browser-only component in Suspense
The next step is to add a Suspense boundary. Suspense is React's mechanism for displaying fallback content while a component is not ready to render. With browser(), that same mechanism represents the period when the server cannot render the component but the browser eventually can.
Here is the complete pattern:
import { Suspense, use, useState } from 'react';
import { browser } from 'react-dom';
function SavedDraft() {
use(browser('The draft requires browser storage.'));
const [draft, setDraft] = useState(
() => localStorage.getItem('draft') ?? ''
);
function handleChange(event) {
const nextDraft = event.target.value;
```
setDraft(nextDraft);
localStorage.setItem('draft', nextDraft);
```
}
return (
);
}
export default function App() {
return (
<>
Saved draft
```
Loading draft...}>
>
```
);
}There are two important pieces here. use(browser()) tells React that SavedDraft should not render on the server, while Suspense provides the HTML that can safely be sent from the server. Once the browser hydrates the application, React can render SavedDraft and access localStorage.
Understand what the server and browser actually render
Suppose the server renders the application above. It does not attempt to execute the browser-only portion of SavedDraft. Instead, the nearest Suspense boundary produces its fallback, so the initial HTML contains the loading message.
After hydration, the browser evaluates use(browser()) successfully. The component can then read localStorage, initialise its state, and replace the fallback with the textarea. This is different from hiding a component with CSS or rendering an empty placeholder: React explicitly knows that the subtree has deferred its rendering to the browser.
The distinction matters for server-rendered sites because the browser-only content is not present in the initial server HTML. If the content is important for search indexing or the first visible page, provide server-renderable data instead of unnecessarily moving that content behind browser().
Use a server-safe value when one is available
Not every browser-dependent value requires a browser-only render. Sometimes the server already knows a useful default. React's documentation demonstrates this pattern with time zones: if a default value is available, render it normally; otherwise, defer the component to the browser.
import { use } from 'react';
import { browser } from 'react-dom';
function TimeZone({ defaultValue }) {
if (defaultValue) {
return Time zone: {defaultValue}
;
}
use(browser('No default time zone was provided.'));
const localTimeZone =
Intl.DateTimeFormat().resolvedOptions().timeZone;
return Time zone: {localTimeZone}
;
}This approach is usually better for content that can be meaningfully represented on the server. A server-provided value gives the user useful HTML immediately, while browser() remains available for cases where only the device can supply the correct value.
Replace the old mounted-state pattern carefully
A common older pattern is to start with a false mounted state and set it to true inside useEffect. That works because the component initially renders a server-safe version and then performs another render after hydration. The drawback is that the component has to manage a temporary state purely to express that it should eventually run in the browser.
function OldBrowserOnly() {
const [mounted, setMounted] = useState(false);
useEffect(() => {
setMounted(true);
}, []);
if (!mounted) {
return Loading...
;
}
return Browser content
;
}With React 19.3, a browser-only component can instead express that requirement directly:
function BrowserOnly() {
use(browser());
return Browser content
;
}The new version does not automatically make every old pattern obsolete. If a component can render useful server HTML and only needs an effect to enhance it later, normal rendering and effects may still be the better design. The browser API is most useful when server rendering the component itself is inappropriate.
Do not call browser() without use()
One easy mistake is treating browser() as a function that performs the browser check by itself. Calling it alone does not mark a component as browser-only. React's documented pattern is to pass the value returned by browser() to the use API.
import { use } from 'react';
import { browser } from 'react-dom';
function BrowserOnly() {
use(browser());
return Rendered in the browser
;
}The reason is architectural: browser() creates the signal React's rendering system understands, while use() consumes that signal. React can then suspend the component during server rendering and allow it to continue during browser rendering.
Check the Suspense boundary before testing
A browser-only component must be inside a Suspense boundary when server rendering is involved. Without that boundary, the server renderer has no fallback to use when use(browser()) suspends, and the server render fails.
For that reason, test the component with the boundary in place rather than adding browser() first and trying to repair the server error afterward. A useful minimal structure is:
Loading...}>
Then test the page in two stages: first inspect the server-generated HTML and confirm that the fallback appears, then load the page in a real browser and confirm that the browser-only component replaces it after hydration.
Keep browser-only code small
The strongest use of the API is usually a small boundary around the code that actually needs the browser. Do not wrap an entire page simply because one widget reads localStorage. Keeping the boundary narrow preserves server-rendered HTML for the rest of the page and makes it easier to understand which part depends on client-only capabilities.
For example, a product page can remain server-rendered while a saved-items indicator uses browser() to access browser storage. A documentation page can render its article on the server while a preference panel reads browser settings after hydration. This separation also makes debugging easier because browser-specific behaviour has a clear boundary.
Test SEO, hydration, and loading behaviour
Before shipping a browser-only component, check the generated HTML rather than testing only the final browser screen. View the page source or inspect the server response and confirm that the expected fallback or server-safe content is present. Then disable JavaScript temporarily and verify that the page still contains the content that should remain available without client rendering.
Next, reload with JavaScript enabled and confirm that hydration replaces the fallback without console errors. Test a fresh browser session as well as a session containing existing localStorage data, because client-side state can expose problems that are invisible in an empty profile. Finally, check slow network conditions so the fallback is useful rather than leaving an unexplained blank area.
React 19.3's browser() API is best viewed as a precise tool for a specific rendering problem: some components simply cannot be meaningfully produced on the server. When that is genuinely the case, let React and Suspense express the boundary directly. When useful server data exists, render that data first and reserve browser-only rendering for the part that truly depends on the device.
Share this post
Written by



