diff --git a/src/content/reference/react/createElement.md b/src/content/reference/react/createElement.md index 87110a71af5..7a67530626c 100644 --- a/src/content/reference/react/createElement.md +++ b/src/content/reference/react/createElement.md @@ -40,7 +40,7 @@ function Greeting({ name }) { * `type`: The `type` argument must be a valid React component type. For example, it could be a tag name string (such as `'div'` or `'span'`), or a React component (a function, a class, or a special component like [`Fragment`](/reference/react/Fragment)). -* `props`: The `props` argument must either be an object or `null`. If you pass `null`, it will be treated the same as an empty object. React will create an element with props matching the `props` you have passed. Note that `ref` and `key` from your `props` object are special and will *not* be available as `element.props.ref` and `element.props.key` on the returned `element`. They will be available as `element.ref` and `element.key`. +* `props`: The `props` argument must either be an object or `null`. If you pass `null`, it will be treated the same as an empty object. React will create an element with props matching the `props` you have passed. React stores `key` separately on the returned element as `element.key`. In React 19, you can read a supplied `ref` as `element.props.ref`. * **optional** `...children`: Zero or more child nodes. They can be any React nodes, including React elements, strings, numbers, [portals](/reference/react-dom/createPortal), empty nodes (`null`, `undefined`, `true`, and `false`), and arrays of React nodes. @@ -49,14 +49,15 @@ function Greeting({ name }) { `createElement` returns a React element object with a few properties: * `type`: The `type` you have passed. -* `props`: The `props` you have passed except for `ref` and `key`. -* `ref`: The `ref` you have passed. If missing, `null`. +* `props`: The props you passed, including `ref` if supplied. React reserves `key`. * `key`: The `key` you have passed, coerced to a string. If missing, `null`. Usually, you'll return the element from your component or make it a child of another element. Although you may read the element's properties, it's best to treat every element as opaque after it's created, and only render it. #### Caveats {/*caveats*/} +* In React 19, `element.ref` is deprecated. Read `element.props.ref` when you need the ref on an existing element. + * You must **treat React elements and their props as [immutable](https://en.wikipedia.org/wiki/Immutable_object)** and never change their contents after creation. In development, React will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) the returned element and its `props` property shallowly to enforce this. * When you use JSX, **you must start a tag with a capital letter to render your own custom component.** In other words, `` is equivalent to `createElement(Something)`, but `` (lowercase) is equivalent to `createElement('something')` (note it's a string, so it will be treated as a built-in HTML tag).