Add experimental docs for Fragment refs#8010
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! 🙌 |
| } | ||
| ``` | ||
|
|
||
| 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
left a comment
eps1lon
left a comment
There was a problem hiding this comment.
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.
| #### 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.
| - <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.
| 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.
| 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
left a comment
slorber
left a comment
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); |
5 participants
Here's a first pass at documenting the Fragment refs feature which is available on experimental builds.