[Suggestion]: Add note with some CSS selector side effects depending on DOM presence to `Activity` troubleshooting

[fufuShih]

Summary

Docs in Activity troubleshooting section,

My hidden components have unwanted side effects, lists <video>, <audio>, and <iframe> as common examples of side effects, but it does not yet cover the category of CSS selectors.

Some common CSS selectors, such as :has() and :is(), may continue to match after the content is hidden by <Activity>, leading to unexpected residual styles.

Page

https://react.dev/reference/react/Activity#troubleshooting

Details

Description

<Activity mode="hidden"> is designed to preserve DOM nodes (applying display: none), which is an intentional design choice. However, most CSS selectors only check the DOM structure and do not consider whether the element is actually visible.

This aligns with the existing explanation in the documentation:

"since a hidden component's DOM is not destroyed, any side effects from that DOM will persist, even after the component is hidden."

The persistent matching of CSS selectors is the exact same kind of DOM side effect, just occurring at the CSS layer,

But, docs doesn't have specific guidance for this type of CSS side effect on DOM. I have some problem to ask for suggestions:

• Does the useLayoutEffect cleanup pattern mentioned in the docs for <video> also apply to handling this kind of CSS side effect?
• Or is this a known limitation of the <Activity> design that should be explicitly stated in the documentation so developers are aware of it in advance?

Affected Selectors

:has()

/* ⚠️ Still applies after PageA is hidden by Activity */
body:has([data-has="a"]) .banner { background: red; }

:is() / :where()

/* ⚠️ Hidden elements are still matched, causing adjacent sibling styles to persist */
:is(section[data-sibling="a"]) ~ .footer { color: red; }
:where([data-page="a"]) .title { font-weight: bold; }

Demo

https://github.com/fufuShih/demo-react-activtiy-problem

The demo have two toggle modes (unmount / activity) and two page comps (A / B):

• HasDemo: Uses body:has([data-has="a"]) .banner to detect if Page A is visible. After switching to Page B, the banner should revert to its default color.
• SiblingDemo: Uses :is(section[data-sibling="a"]) ~ .footer to detect adjacent sibling elements. After switching to Page B, the footer should revert to its default color.

Both behave normally in unmount mode. However, when switched to activity mode, Page A is hidden by <Activity mode="hidden"> but remains in the DOM, causing both selectors to continue matching and preventing the styles from resetting.