Clarify browser-only rendering guidance - #8612
Merged
aurorascharff merged 11 commits intoAug 19, 2026
Merged
Conversation
Size changesDetails📦 Next.js Bundle Analysis for react-devThis analysis was generated by the Next.js Bundle Analysis action. 🤖 This PR introduced no changes to the JavaScript bundle! 🙌 |
aurorascharff
marked this pull request as ready for review
August 19, 2026 18:29
aurorascharff
marked this pull request as draft
August 19, 2026 18:39
aurorascharff
marked this pull request as ready for review
August 19, 2026 18:45
gaearon
reviewed
Aug 19, 2026
gaearon
reviewed
Aug 19, 2026
gaearon
reviewed
Aug 19, 2026
gaearon
reviewed
Aug 19, 2026
gaearon
reviewed
Aug 19, 2026
|
|
||
| Use this approach when you want the client-rendered content to be different from the initial server-rendered HTML. | ||
|
|
||
| <Canary>If a component should render only in the browser, call [`use(browser())`](/reference/react/use#use-browser) instead of waiting for an Effect.</Canary> |
Member
There was a problem hiding this comment.
Note we should probably delete this entire subsection once this ships in stable?
gaearon
reviewed
Aug 19, 2026
| <Intro> | ||
|
|
||
| `use` is a React API that lets you read the value of a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [context](/learn/passing-data-deeply-with-context). | ||
| `use` is a React API that lets you read the value of a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) or [context](/learn/passing-data-deeply-with-context). You can also call `use` with the opaque value returned by [`browser`](/reference/react-dom/browser) to mark a component as browser-only during server rendering. |
Member
There was a problem hiding this comment.
This feels a bit disproportionate:
Any ideas for how to compress it so that it doesn't take 80% of the explanation for a rare case?
gaearon
approved these changes
Aug 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
browservalue in theuseintroduction and Built-in React APIs overviewuse(browser())its own usage group instead of nesting it under Promise usageuseLayoutEffectserver-rendering guidance to the Canary browser-only APIWhy
The
browserAPI reference and examples landed in #8582, but nearby documentation still describeduseas accepting only Promises and context or presented older browser-only workarounds without mentioning the dedicated Canary API. This follow-up connects those existing entry points while preserving the guidance needed by stable React releases.Validation
yarn lint-heading-idsyarn deadlinks(all 1,900 links valid)yarn build(all 816 static pages and 219 OG images generated)