Unverified Commit c77d47fc authored by Joseph's avatar Joseph Committed by GitHub

docs: Activity bfcacheId and :has caveats (#95275)

- x-ref to `bfcacheId`
- add a section on `:has`

---------
Co-authored-by: 's avatarvercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
parent 7b68a313
...@@ -18,7 +18,7 @@ Instead of unmounting pages on navigation, Next.js hides them using React's [`<A ...@@ -18,7 +18,7 @@ Instead of unmounting pages on navigation, Next.js hides them using React's [`<A
Next.js preserves up to 3 routes. Beyond that, the oldest route is evicted and will re-render fresh. Next.js preserves up to 3 routes. Beyond that, the oldest route is evicted and will re-render fresh.
> **Good to know:** Opt-out strategies are being considered for gradual migration. > **Good to know:** Use [`useRouter().bfcacheId`](/docs/app/api-reference/functions/use-router#bfcacheid) as a [React `key`](https://react.dev/learn/preserving-and-resetting-state#option-2-resetting-state-with-a-key): a single `<Fragment key={bfcacheId}>` resets an entire subtree on push or replace navigations (including `<Link>` clicks and `router.push` / `router.replace`) while still restoring state on browser back/forward. `bfcacheId` is mainly a migration tool. For new code, prefer the per-pattern resets below.
## Choosing what to preserve ## Choosing what to preserve
...@@ -322,6 +322,34 @@ function PageWithStyles() { ...@@ -322,6 +322,34 @@ function PageWithStyles() {
When Activity hides the component, the cleanup sets `media="not all"`, which disables the stylesheet. When visible again, the effect re-runs and resets `media` to enable it. When Activity hides the component, the cleanup sets `media="not all"`, which disables the stylesheet. When visible again, the effect re-runs and resets `media` to enable it.
### The `:has` selector
A [`:root:has(...)`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:has) rule applies styles based on its selector. Neither the selected element nor the matched element knows about the relationship. It's valid CSS, but it bypasses React's data flow and couples unrelated components.
For global state, prefer a `data-*` attribute that React owns:
```tsx
<html data-modal-open={modalOpen ? "true" : undefined}>
```
```css
html[data-modal-open='true'] {
overflow: hidden;
}
```
Reserve `:has()` for local parent/child styling within a component:
```css
.card:has(img) {
padding-top: 0;
}
```
This isn't only a React data-flow or Next.js concern. Broad `:has()` selectors are a real performance bottleneck. See [Performance considerations](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:has#performance_considerations) on MDN.
> **Good to know:** If the hidden component itself defines the global `:has` rule, the toggle from the section above disables it along with the component's other styles.
## Testing ## Testing
Hidden Activity content has `display: none` but remains in the document. This applies both to routes preserved by Cache Components and to content you hide with `<Activity>` directly. It affects end-to-end testing with tools like Playwright, Cypress, or Puppeteer: Hidden Activity content has `display: none` but remains in the document. This applies both to routes preserved by Cache Components and to content you hide with `<Activity>` directly. It affects end-to-end testing with tools like Playwright, Cypress, or Puppeteer:
......
...@@ -174,7 +174,7 @@ export default function Page() { ...@@ -174,7 +174,7 @@ export default function Page() {
} }
``` ```
When `cacheComponents` is enabled, the App Router preserves Client Component state across navigations using React `<Activity>`. Keying a component on `bfcacheId` resets it on each fresh navigation while still preserving its state across browser back/forward navigations. When `cacheComponents` is enabled, the App Router preserves Client Component state across navigations using React `<Activity>`. Keying a component on `bfcacheId` resets it on each fresh navigation while still preserving its state across browser back/forward navigations. See [Preserving UI state](/docs/app/guides/preserving-ui-state) for the recommended per-pattern resets.
> **Good to know**: > **Good to know**:
> Instead of `bfcacheId`, prefer resetting state explicitly in an event handler (for example, `onSubmit`) or deriving a key from your data (for example, a draft id from the server). Use `bfcacheId` only as a last resort, like when migrating an existing codebase. > Instead of `bfcacheId`, prefer resetting state explicitly in an event handler (for example, `onSubmit`) or deriving a key from your data (for example, a draft id from the server). Use `bfcacheId` only as a last resort, like when migrating an existing codebase.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment