Docs for new DOM APIs by rubennorte · Pull Request #4783 · react/react-native-website

rubennorte · 2025-09-09T14:48:26Z

This adds the initial documentation for the new Web DOM APIs in React Native, that will be shipped as stable in React Native v0.82.

netlify · 2025-09-09T14:52:25Z

✅ Deploy Preview for react-native ready!

Name	Link
🔨 Latest commit	`5982a37`
🔍 Latest deploy log	https://app.netlify.com/projects/react-native/deploys/68c03e3d63624a00086c199a
😎 Deploy Preview	https://deploy-preview-4783--react-native.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-09-09T14:54:15Z

✅ Deploy Preview for react-native ready!

Name	Link
🔨 Latest commit	`a035c1f`
🔍 Latest deploy log	https://app.netlify.com/projects/react-native/deploys/68d17d887a376e0008215c9d
😎 Deploy Preview	https://deploy-preview-4783--react-native.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

cortinico · 2025-09-10T17:42:42Z

+export default ViewWithRefs;
+```
+
+Note that some built-in components are only a container for other components (including native components). For example, `ScrollView` internally renders a native scroll view and a native view, which are accessible through the ref is provides using methods like `getNativeScrollRef()` and `getInnerViewRef()`.


which are accessible through the ref is provides using methods like getNativeScrollRef() and getInnerViewRef().

There is something wrong in this sentence

through the ref it provides...

Will fix :)

cortinico · 2025-09-10T17:42:53Z

+
+export default ViewWithRefs;
+```
+


Can you put the box below inside an :::info box?

cortinico · 2025-09-10T17:43:20Z

+  - [`offsetWidth`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetWidth)
+- Methods
+  - [`blur()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur).
+    - ℹ️ This method was also [available](/docs/next/legacy/direct-manipulation#blur) in the legacy architecture.


Not sure this is worth mentioning anymore

cortinico · 2025-09-10T17:44:57Z

+- [Text](/docs/next/text-nodes): text nodes represent raw text content on the tree (similar to [`Text`](https://developer.mozilla.org/en-US/docs/Web/API/Text) nodes on Web). They are not directly accessible via `refs`, but can be accessed using methods like [`childNodes`](https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes) on element refs.
+- [Documents](/docs/next/document-nodes): document nodes represent a complete native view tree (similar to [`Document`](https://developer.mozilla.org/en-US/docs/Web/API/Document) nodes on Web). Like text nodes, they can only be accessed through other nodes, using properties like [`ownerDocument`](https://developer.mozilla.org/en-US/docs/Web/API/Node/ownerDocument).
+
+As on Web, these nodes can be used to traverse the rendered UI tree, access layout information or execute imperative operations like `focus`. **Unlike on Web, they do not allow mutation** (e.g.: [`node.appendChild`](https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild)), as the tree contents are fully managed by the React renderer.


Unlike on Web, they do not allow mutation

Can you put this in a separate line + add it in a admonition box (like a :::warning one or so)?

Yeah, but will use info instead of warning. We're already explaining the methods we support, and none of the mutating ones are even defined.

cortinico

LGTM. Left a couple of comments

cortinico · 2025-09-22T14:01:38Z

+### Legacy API
+
+- [`measure()`](/docs/next/legacy/direct-manipulation#measurecallback)
+- [`measureInWindow()`](/docs/next/legacy/direct-manipulation#measureinwindowcallback)
+- [`measureLayout()`](/docs/next/legacy/direct-manipulation#measurelayoutrelativetonativecomponentref-onsuccess-onfail)
+- [`setNativeProps()`](/docs/next/legacy/direct-manipulation#setnativeprops-with-touchableopacity)


Should those be removed altogether?

Not if you want to keep backwards compatibility.

cortinico · 2025-09-22T14:02:49Z


 ---

+### `modalRef`


Why is this called modalRef and not ref as all the others?

I saw that as the name of the prop in the component, but I checked again and it's exposed as both. Will keep ref instead.

rickhanlonii · 2025-09-22T15:52:21Z

+
+  return (
+      <View ref={instance => {
+        if (instance != null) {


Can we use callback refs with a cleanup instead of the legacy null check?

rickhanlonii · 2025-09-22T15:53:20Z

+        style={styles.content}
+        ref={(instance) => {
+          // `instance` is an object implementing the interface described here,
+          // or `null` when the component is unmounted.


Same here: return a cleanup instead (and all the docs, won't comment each one).

rickhanlonii · 2025-09-22T15:54:14Z

+
+As on Web, these nodes can be used to traverse the rendered UI tree, access layout information or execute imperative operations like `focus`.
+
+:::info


rickhanlonii · 2025-09-22T15:55:00Z


+### `ref`
+
+A ref setter that will be assigned an [element node](element-nodes) when mounted.


Is this an element node or should it be a text node?

It's an element node. This would be equivalent to a paragraph node on Web, not to its underlying text node.

I can clarify that in the docs.

rickhanlonii

LGTM, left some notes

meta-cla Bot added the CLA Signed label Sep 9, 2025

facebook-github-bot added p: Facebook Partner labels Sep 9, 2025

rubennorte force-pushed the dom-apis branch from 5982a37 to 322cb1e Compare September 9, 2025 14:50

rubennorte force-pushed the dom-apis branch 3 times, most recently from 9528808 to 55fe11c Compare September 9, 2025 15:43

rubennorte requested review from cipolleschi, cortinico, lunaleaps and rickhanlonii September 9, 2025 15:46

rubennorte force-pushed the dom-apis branch from 55fe11c to 8eb45e8 Compare September 9, 2025 17:39

cortinico approved these changes Sep 10, 2025

View reviewed changes

rubennorte force-pushed the dom-apis branch from 8eb45e8 to 2db9536 Compare September 11, 2025 09:07

rubennorte requested a review from cortinico September 11, 2025 09:20

rubennorte added 2 commits September 22, 2025 12:30

Docs for new DOM APIs

961e1f1

Address first round of comments

7669b58

rubennorte force-pushed the dom-apis branch from 2db9536 to 94c9fca Compare September 22, 2025 11:30

cortinico approved these changes Sep 22, 2025

View reviewed changes

Reference new ref API in components API reference

d4cee9f

rubennorte force-pushed the dom-apis branch from 94c9fca to d4cee9f Compare September 22, 2025 15:03

rickhanlonii reviewed Sep 22, 2025

View reviewed changes

rickhanlonii approved these changes Sep 22, 2025

View reviewed changes

rubennorte added 2 commits September 22, 2025 17:36

Address feedback about examples and clarify Text component refs

c548a05

Fix examples

a035c1f

rubennorte merged commit e1c84f1 into react:main Sep 22, 2025
4 checks passed

rubennorte deleted the dom-apis branch September 22, 2025 17:32


		As on Web, these nodes can be used to traverse the rendered UI tree, access layout information or execute imperative operations like `focus`.

		:::info


		### `ref`

		A ref setter that will be assigned an [element node](element-nodes) when mounted.


		export default ViewWithRefs;
		```

Conversation

rubennorte commented Sep 9, 2025

Uh oh!

netlify Bot commented Sep 9, 2025

✅ Deploy Preview for react-native ready!

Uh oh!

netlify Bot commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for react-native ready!

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!

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!

cortinico 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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rickhanlonii left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify Bot commented Sep 9, 2025 •

edited

Loading