Add experimental docs for Fragment refs #8010
Merged
Conversation
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
Size changes📦 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! 🙌 |
| } | ||
| ``` | ||
| This pattern is an alternative to effect-based visibility logging, which is usually not what you want since you don't know of the element you're targeting is in the viewport. |
There was a problem hiding this comment.
nit: "not what you want" feels a bit too casual and imprecise for the docs
eps1lon
reviewed
Oct 3, 2025
| #### Props {/*props*/} | ||
|
|
||
| - **optional** `key`: Fragments declared with the explicit `<Fragment>` syntax may have [keys.](/learn/rendering-lists#keeping-list-items-in-order-with-key) | ||
| - <ExperimentalBadge /> **optional** `ref`: A ref object or callback function. React will forward the ref to a `FragmentInstance` object that provides methods for interacting with the DOM nodes wrapped by the Fragment. |
There was a problem hiding this comment.
Suggested change
| - <ExperimentalBadge /> **optional** `ref`: A ref object or callback function. React will forward the ref to a `FragmentInstance` object that provides methods for interacting with the DOM nodes wrapped by the Fragment. | |
| - <ExperimentalBadge /> **optional** `ref`: A ref object (e.g. from [`useRef`](/reference/react/useRef)) or [callback function](/reference/react-dom/components/common#ref-callback). React provides a `FragmentInstance` in the ref value that implements methods for interacting with the DOM nodes wrapped by the Fragment. |
| } | ||
| ``` | ||
| This pattern is an alternative to effect-based visibility logging, which is an anti-pattern in most cases. Relying on effects alone does not guarantee that the rendered component is observable by the user. |
There was a problem hiding this comment.
Suggested change
| This pattern is an alternative to effect-based visibility logging, which is an anti-pattern in most cases. Relying on effects alone does not guarantee that the rendered component is observable by the user. | |
| This pattern is an alternative to effect-based visibility logging, which is an anti-pattern in most cases. Relying on Effects alone does not guarantee that the rendered Component is observable by the user. |
| ### <ExperimentalBadge /> Tracking visibility with Fragment refs {/*tracking-visibility-with-fragment-refs*/} | ||
| Fragment refs are useful for visibility tracking and intersection observation. This enables you to monitor when content becomes visible without requiring the child components to expose refs: |
There was a problem hiding this comment.
Suggested change
| Fragment refs are useful for visibility tracking and intersection observation. This enables you to monitor when content becomes visible without requiring the child components to expose refs: | |
| Fragment refs are useful for visibility tracking and intersection observation. This enables you to monitor when content becomes visible without requiring the child Components to expose refs: |
|
We don't say "host" in docs. The common approach so far has been to just say DOM and imply that native has "its own DOM". Which kind of aligns with the DOM-like APIs that RN is adding but may be a bit confusing. I think it's fine though and can be called out separately. |
slorber
reviewed
Oct 7, 2025
There was a problem hiding this comment.
See 2 comments
Also, isn''t scrollIntoView() docs missing? (cf facebook/react#34720)
| - Empty Fragments will attempt to compare positioning within the React tree and include `Node.DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC`. | ||
| - Elements that have a different relationship in the React tree and DOM tree due to portaling or other insertions are `Node.DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC`. | ||
| - `getClientRects()`: Returns a flat array of `DOMRect` objects representing the bounding rectangles of all children. | ||
| - `getRootNode()`: Returns the root node containing the Fragment's parent DOM node. |
There was a problem hiding this comment.
Dumb question but why can we easily get the root node, but not the parent node?
Wouldn't this be more flexible alternative to findDOMNode? fragmentRef.current.parent.getRootNode() ?
| import { Fragment, useRef } from 'react'; | ||
|
|
||
| function FocusFragment({ children }) { | ||
| const fragmentRef = useRef(null); |
There was a problem hiding this comment.
looks like a typo, PR #8056
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Here's a first pass at documenting the Fragment refs feature which is available on experimental builds.