Add experimental docs for Fragment refs by jackpope · Pull Request #8010 · reactjs/react.dev

jackpope · 2025-09-23T18:04:41Z

Here's a first pass at documenting the Fragment refs feature which is available on experimental builds.

github-actions · 2025-09-23T18:08:39Z

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

josephsavona · 2025-09-26T16:56:05Z

+}
+```
+
+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.


nit: "not what you want" feels a bit too casual and imprecise for the docs

eps1lon

Have we introduced the concept of "Host Components" somewhere else? This isn't just specific to DOM nodes but the Host Components of a specific renderer. The DOM is only one example. Native is another.

eps1lon · 2025-10-03T13:33:36Z

 #### 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.


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.

eps1lon · 2025-10-03T13:36:58Z

+}
+```
+
+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.


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.

eps1lon · 2025-10-03T13:37:10Z

+
+### <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:


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:

eps1lon

non-blocking review above.

gaearon · 2025-10-03T14:08:53Z

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

See 2 comments

Also, isn''t scrollIntoView() docs missing? (cf react/react#34720)

slorber · 2025-10-07T15:38:37Z

+ - 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.


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() ?

slorber · 2025-10-07T15:39:01Z

+import { Fragment, useRef } from 'react';
+
+function FocusFragment({ children }) {
+ const fragmentRef = useRef(null);


looks like a typo, PR #8056

jackpope · 2025-09-23T18:04:41Z

Here's a first pass at documenting the Fragment refs feature which is available on experimental builds.

github-actions · 2025-09-23T18:08:39Z

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

josephsavona · 2025-09-26T16:56:05Z

+}
+```
+
+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.


nit: "not what you want" feels a bit too casual and imprecise for the docs

eps1lon

Have we introduced the concept of "Host Components" somewhere else? This isn't just specific to DOM nodes but the Host Components of a specific renderer. The DOM is only one example. Native is another.

eps1lon · 2025-10-03T13:33:36Z

 #### 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.


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.

eps1lon · 2025-10-03T13:36:58Z

+}
+```
+
+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.


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.

eps1lon · 2025-10-03T13:37:10Z

+
+### <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:


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:

eps1lon

non-blocking review above.

gaearon · 2025-10-03T14:08:53Z

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

See 2 comments

Also, isn''t scrollIntoView() docs missing? (cf react/react#34720)

slorber · 2025-10-07T15:38:37Z

+ - 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.


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() ?

slorber · 2025-10-07T15:39:01Z

+import { Fragment, useRef } from 'react';
+
+function FocusFragment({ children }) {
+ const fragmentRef = useRef(null);


looks like a typo, PR #8056

jackpope · 2025-09-23T18:04:41Z

Here's a first pass at documenting the Fragment refs feature which is available on experimental builds.

github-actions · 2025-09-23T18:08:39Z

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

josephsavona · 2025-09-26T16:56:05Z

+}
+```
+
+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.


nit: "not what you want" feels a bit too casual and imprecise for the docs

eps1lon

Have we introduced the concept of "Host Components" somewhere else? This isn't just specific to DOM nodes but the Host Components of a specific renderer. The DOM is only one example. Native is another.

eps1lon · 2025-10-03T13:33:36Z

 #### 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.


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.

eps1lon · 2025-10-03T13:36:58Z

+}
+```
+
+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.


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.

eps1lon · 2025-10-03T13:37:10Z

+
+### <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:


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:

eps1lon

non-blocking review above.

gaearon · 2025-10-03T14:08:53Z

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

See 2 comments

Also, isn''t scrollIntoView() docs missing? (cf react/react#34720)

slorber · 2025-10-07T15:38:37Z

+ - 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.


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() ?

slorber · 2025-10-07T15:39:01Z

+import { Fragment, useRef } from 'react';
+
+function FocusFragment({ children }) {
+ const fragmentRef = useRef(null);


looks like a typo, PR #8056

jackpope · 2025-09-23T18:04:41Z

Here's a first pass at documenting the Fragment refs feature which is available on experimental builds.

github-actions · 2025-09-23T18:08:39Z

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

josephsavona · 2025-09-26T16:56:05Z

+}
+```
+
+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.


nit: "not what you want" feels a bit too casual and imprecise for the docs

eps1lon

Have we introduced the concept of "Host Components" somewhere else? This isn't just specific to DOM nodes but the Host Components of a specific renderer. The DOM is only one example. Native is another.

eps1lon · 2025-10-03T13:33:36Z

 #### 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.


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.

eps1lon · 2025-10-03T13:36:58Z

+}
+```
+
+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.


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.

eps1lon · 2025-10-03T13:37:10Z

+
+### <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:


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:

eps1lon

non-blocking review above.

gaearon · 2025-10-03T14:08:53Z

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

See 2 comments

Also, isn''t scrollIntoView() docs missing? (cf react/react#34720)

slorber · 2025-10-07T15:38:37Z

+ - 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.


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() ?

slorber · 2025-10-07T15:39:01Z

+import { Fragment, useRef } from 'react';
+
+function FocusFragment({ children }) {
+ const fragmentRef = useRef(null);


looks like a typo, PR #8056

jackpope · 2025-09-23T18:04:41Z

Here's a first pass at documenting the Fragment refs feature which is available on experimental builds.

github-actions · 2025-09-23T18:08:39Z

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

josephsavona · 2025-09-26T16:56:05Z

+}
+```
+
+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.


nit: "not what you want" feels a bit too casual and imprecise for the docs

eps1lon

Have we introduced the concept of "Host Components" somewhere else? This isn't just specific to DOM nodes but the Host Components of a specific renderer. The DOM is only one example. Native is another.

eps1lon · 2025-10-03T13:33:36Z

 #### 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.


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.

eps1lon · 2025-10-03T13:36:58Z

+}
+```
+
+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.


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.

eps1lon · 2025-10-03T13:37:10Z

+
+### <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:


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:

eps1lon

non-blocking review above.

gaearon · 2025-10-03T14:08:53Z

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

See 2 comments

Also, isn''t scrollIntoView() docs missing? (cf react/react#34720)

slorber · 2025-10-07T15:38:37Z

+ - 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.


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() ?

slorber · 2025-10-07T15:39:01Z

+import { Fragment, useRef } from 'react';
+
+function FocusFragment({ children }) {
+ const fragmentRef = useRef(null);


looks like a typo, PR #8056

jackpope · 2025-09-23T18:04:41Z

Here's a first pass at documenting the Fragment refs feature which is available on experimental builds.

github-actions · 2025-09-23T18:08:39Z

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

josephsavona · 2025-09-26T16:56:05Z

+}
+```
+
+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.


nit: "not what you want" feels a bit too casual and imprecise for the docs

eps1lon

Have we introduced the concept of "Host Components" somewhere else? This isn't just specific to DOM nodes but the Host Components of a specific renderer. The DOM is only one example. Native is another.

eps1lon · 2025-10-03T13:33:36Z

 #### 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.


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.

eps1lon · 2025-10-03T13:36:58Z

+}
+```
+
+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.


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.

eps1lon · 2025-10-03T13:37:10Z

+
+### <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:


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:

eps1lon

non-blocking review above.

gaearon · 2025-10-03T14:08:53Z

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

See 2 comments

Also, isn''t scrollIntoView() docs missing? (cf react/react#34720)

slorber · 2025-10-07T15:38:37Z

+ - 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.


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() ?

slorber · 2025-10-07T15:39:01Z

+import { Fragment, useRef } from 'react';
+
+function FocusFragment({ children }) {
+ const fragmentRef = useRef(null);


looks like a typo, PR #8056

jackpope · 2025-09-23T18:04:41Z

Here's a first pass at documenting the Fragment refs feature which is available on experimental builds.

github-actions · 2025-09-23T18:08:39Z

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

josephsavona · 2025-09-26T16:56:05Z

+}
+```
+
+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.


nit: "not what you want" feels a bit too casual and imprecise for the docs

eps1lon

Have we introduced the concept of "Host Components" somewhere else? This isn't just specific to DOM nodes but the Host Components of a specific renderer. The DOM is only one example. Native is another.

eps1lon · 2025-10-03T13:33:36Z

 #### 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.


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.

eps1lon · 2025-10-03T13:36:58Z

+}
+```
+
+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.


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.

eps1lon · 2025-10-03T13:37:10Z

+
+### <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:


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:

eps1lon

non-blocking review above.

gaearon · 2025-10-03T14:08:53Z

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

See 2 comments

Also, isn''t scrollIntoView() docs missing? (cf react/react#34720)

slorber · 2025-10-07T15:38:37Z

+ - 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.


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() ?

slorber · 2025-10-07T15:39:01Z

+import { Fragment, useRef } from 'react';
+
+function FocusFragment({ children }) {
+ const fragmentRef = useRef(null);


looks like a typo, PR #8056

jackpope · 2025-09-23T18:04:41Z

Here's a first pass at documenting the Fragment refs feature which is available on experimental builds.

github-actions · 2025-09-23T18:08:39Z

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

josephsavona · 2025-09-26T16:56:05Z

+}
+```
+
+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.


nit: "not what you want" feels a bit too casual and imprecise for the docs

eps1lon

Have we introduced the concept of "Host Components" somewhere else? This isn't just specific to DOM nodes but the Host Components of a specific renderer. The DOM is only one example. Native is another.

eps1lon · 2025-10-03T13:33:36Z

 #### 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.


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.

eps1lon · 2025-10-03T13:36:58Z

+}
+```
+
+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.


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.

eps1lon · 2025-10-03T13:37:10Z

+
+### <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:


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:

eps1lon

non-blocking review above.

gaearon · 2025-10-03T14:08:53Z

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

See 2 comments

Also, isn''t scrollIntoView() docs missing? (cf react/react#34720)

slorber · 2025-10-07T15:38:37Z

+ - 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.


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() ?

slorber · 2025-10-07T15:39:01Z

+import { Fragment, useRef } from 'react';
+
+function FocusFragment({ children }) {
+ const fragmentRef = useRef(null);


looks like a typo, PR #8056

Add experimental docs for Fragment refs
37a3b84

meta-claBot added the CLA Signed label Sep 23, 2025

github-actionsBot added the React Core Team label Sep 23, 2025

vercelBotdeployed to Preview September 23, 2025 18:05 View deployment

josephsavona reviewed Sep 26, 2025
View reviewed changes

Update wording
3996b92

vercelBotdeployed to Preview September 26, 2025 21:39 View deployment

eps1lon reviewed Oct 3, 2025
View reviewed changes

eps1lon approved these changes Oct 3, 2025
View reviewed changes

Address feedback
e37bd7c

vercelBotdeployed to Preview October 3, 2025 14:32 View deployment

jackpope merged commit ae584af into mainOct 3, 2025
6 checks passed

jackpope deleted the fragment-refs-docs branch October 3, 2025 14:36

slorber reviewed Oct 7, 2025
View reviewed changes

Add experimental docs for Fragment refs
37a3b84

meta-claBot added the CLA Signed label Sep 23, 2025

github-actionsBot added the React Core Team label Sep 23, 2025

vercelBotdeployed to Preview September 23, 2025 18:05 View deployment

josephsavona reviewed Sep 26, 2025
View reviewed changes

Update wording
3996b92

vercelBotdeployed to Preview September 26, 2025 21:39 View deployment

eps1lon reviewed Oct 3, 2025
View reviewed changes

eps1lon approved these changes Oct 3, 2025
View reviewed changes

Address feedback
e37bd7c

vercelBotdeployed to Preview October 3, 2025 14:32 View deployment

jackpope merged commit ae584af into mainOct 3, 2025
6 checks passed

jackpope deleted the fragment-refs-docs branch October 3, 2025 14:36

slorber reviewed Oct 7, 2025
View reviewed changes

Add experimental docs for Fragment refs
37a3b84

meta-claBot added the CLA Signed label Sep 23, 2025

github-actionsBot added the React Core Team label Sep 23, 2025

vercelBotdeployed to Preview September 23, 2025 18:05 View deployment

josephsavona reviewed Sep 26, 2025
View reviewed changes

Update wording
3996b92

vercelBotdeployed to Preview September 26, 2025 21:39 View deployment

eps1lon reviewed Oct 3, 2025
View reviewed changes

eps1lon approved these changes Oct 3, 2025
View reviewed changes

Address feedback
e37bd7c

vercelBotdeployed to Preview October 3, 2025 14:32 View deployment

jackpope merged commit ae584af into mainOct 3, 2025
6 checks passed

jackpope deleted the fragment-refs-docs branch October 3, 2025 14:36

slorber reviewed Oct 7, 2025
View reviewed changes

Add experimental docs for Fragment refs
37a3b84

meta-claBot added the CLA Signed label Sep 23, 2025

github-actionsBot added the React Core Team label Sep 23, 2025

vercelBotdeployed to Preview September 23, 2025 18:05 View deployment

josephsavona reviewed Sep 26, 2025
View reviewed changes

Update wording
3996b92

vercelBotdeployed to Preview September 26, 2025 21:39 View deployment

eps1lon reviewed Oct 3, 2025
View reviewed changes

eps1lon approved these changes Oct 3, 2025
View reviewed changes

Address feedback
e37bd7c

vercelBotdeployed to Preview October 3, 2025 14:32 View deployment

jackpope merged commit ae584af into mainOct 3, 2025
6 checks passed

jackpope deleted the fragment-refs-docs branch October 3, 2025 14:36

slorber reviewed Oct 7, 2025
View reviewed changes

Add experimental docs for Fragment refs
37a3b84

meta-claBot added the CLA Signed label Sep 23, 2025

github-actionsBot added the React Core Team label Sep 23, 2025

vercelBotdeployed to Preview September 23, 2025 18:05 View deployment

josephsavona reviewed Sep 26, 2025
View reviewed changes

Update wording
3996b92

vercelBotdeployed to Preview September 26, 2025 21:39 View deployment

eps1lon reviewed Oct 3, 2025
View reviewed changes

eps1lon approved these changes Oct 3, 2025
View reviewed changes

Address feedback
e37bd7c

vercelBotdeployed to Preview October 3, 2025 14:32 View deployment

jackpope merged commit ae584af into mainOct 3, 2025
6 checks passed

jackpope deleted the fragment-refs-docs branch October 3, 2025 14:36

slorber reviewed Oct 7, 2025
View reviewed changes

Add experimental docs for Fragment refs
37a3b84

meta-claBot added the CLA Signed label Sep 23, 2025

github-actionsBot added the React Core Team label Sep 23, 2025

vercelBotdeployed to Preview September 23, 2025 18:05 View deployment

josephsavona reviewed Sep 26, 2025
View reviewed changes

Update wording
3996b92

vercelBotdeployed to Preview September 26, 2025 21:39 View deployment

eps1lon reviewed Oct 3, 2025
View reviewed changes

eps1lon approved these changes Oct 3, 2025
View reviewed changes

Address feedback
e37bd7c

vercelBotdeployed to Preview October 3, 2025 14:32 View deployment

jackpope merged commit ae584af into mainOct 3, 2025
6 checks passed

jackpope deleted the fragment-refs-docs branch October 3, 2025 14:36

slorber reviewed Oct 7, 2025
View reviewed changes

Add experimental docs for Fragment refs
37a3b84

meta-claBot added the CLA Signed label Sep 23, 2025

github-actionsBot added the React Core Team label Sep 23, 2025

vercelBotdeployed to Preview September 23, 2025 18:05 View deployment

josephsavona reviewed Sep 26, 2025
View reviewed changes

Update wording
3996b92

vercelBotdeployed to Preview September 26, 2025 21:39 View deployment

eps1lon reviewed Oct 3, 2025
View reviewed changes

eps1lon approved these changes Oct 3, 2025
View reviewed changes

Address feedback
e37bd7c

vercelBotdeployed to Preview October 3, 2025 14:32 View deployment

jackpope merged commit ae584af into mainOct 3, 2025
6 checks passed

jackpope deleted the fragment-refs-docs branch October 3, 2025 14:36

slorber reviewed Oct 7, 2025
View reviewed changes

Add experimental docs for Fragment refs
37a3b84

meta-claBot added the CLA Signed label Sep 23, 2025

github-actionsBot added the React Core Team label Sep 23, 2025

vercelBotdeployed to Preview September 23, 2025 18:05 View deployment

josephsavona reviewed Sep 26, 2025
View reviewed changes

Update wording
3996b92

vercelBotdeployed to Preview September 26, 2025 21:39 View deployment

eps1lon reviewed Oct 3, 2025
View reviewed changes

eps1lon approved these changes Oct 3, 2025
View reviewed changes

Address feedback
e37bd7c

vercelBotdeployed to Preview October 3, 2025 14:32 View deployment

jackpope merged commit ae584af into mainOct 3, 2025
6 checks passed

jackpope deleted the fragment-refs-docs branch October 3, 2025 14:36

slorber reviewed Oct 7, 2025
View reviewed changes

	- <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.
	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:

Uh oh!

Conversation

jackpope commented Sep 23, 2025

Uh oh!

github-actionsBot commented Sep 23, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Size changes

📦 Next.js Bundle Analysis for react-dev

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eps1lon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eps1lon left a comment

Choose a reason for hiding this comment

Uh oh!

gaearon commented Oct 3, 2025

Uh oh!

Uh oh!

slorber left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

jackpope commented Sep 23, 2025

Uh oh!

github-actionsBot commented Sep 23, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Size changes

📦 Next.js Bundle Analysis for react-dev

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eps1lon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eps1lon left a comment

Choose a reason for hiding this comment

Uh oh!

gaearon commented Oct 3, 2025

Uh oh!

Uh oh!

slorber left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

github-actionsBot commented Sep 23, 2025•
edited
Loading

github-actionsBot commented Sep 23, 2025•
edited
Loading

github-actionsBot commented Sep 23, 2025•
edited
Loading