diff --git a/src/content/reference/react-dom/components/img.md b/src/content/reference/react-dom/components/img.md new file mode 100644 index 00000000000..4a1f45077b8 --- /dev/null +++ b/src/content/reference/react-dom/components/img.md @@ -0,0 +1,257 @@ +--- +title: "" +--- + + + +The [built-in browser `` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img) lets you embed an image. + +```js +A person walking through a park +``` + + + + + +--- + +## Reference {/*reference*/} + +### `` {/*img*/} + +To display an image, render the [built-in browser `` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img). + +```js +A person walking through a park +``` + +[See more examples below.](#usage) + +#### Props {/*props*/} + +`` supports all [common element props.](/reference/react-dom/components/common#common-props) + +* `alt`: a string. Specifies alternative text for the image. Use an empty string for a purely decorative image. +* `crossOrigin`: a string. Specifies the [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use when fetching the image. The possible values are `anonymous` and `use-credentials`. +* `decoding`: a string. Suggests whether the browser should wait to decode the image before presenting other content. The possible values are `async`, `sync`, and `auto` (the default). +* `fetchPriority`: a string. Suggests a relative priority for fetching the image. The possible values are `high`, `low`, and `auto` (the default). During server rendering, `fetchPriority="low"` also prevents React from [automatically preloading the image.](#controlling-image-preloading-during-server-rendering) +* `height`: a number or string. Specifies the rendered height of the image. +* `loading`: a string. Specifies whether the browser should defer loading the image until it is near the viewport. The possible values are `eager` (the default) and `lazy`. Setting `loading="lazy"` prevents React from [automatically preloading the image.](#controlling-image-preloading-during-server-rendering) +* `onError`: an [event handler](/reference/react-dom/components/common#event-handler) function. Fires when the image fails to load. +* `onLoad`: an [event handler](/reference/react-dom/components/common#event-handler) function. Fires when the image finishes loading. Passing `onLoad` prevents React from [waiting for the image during a client-rendered View Transition update.](#waiting-for-an-image-during-a-view-transition) +* `referrerPolicy`: a string. Specifies the [referrer information](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy) to send when fetching the image. +* `sizes`: a string. Specifies the image sizes for different page layouts. Used with `srcSet`. +* `src`: a string. Specifies the URL of the image. +* `srcSet`: a string. Specifies one or more candidate image sources for the browser to choose from. +* `useMap`: a string. Associates the image with a [client-side image map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/map). +* `width`: a number or string. Specifies the rendered width of the image. + +#### Caveats {/*caveats*/} + +* Do not pass an empty string to `src`. It may cause the browser to request the current page again. React warns in development and omits the attribute. To render no image, omit the `` or pass `null` to `src`. +* `` cannot have children or use `dangerouslySetInnerHTML`. React throws an error if you pass either. +* `fetchPriority="low"` does not stop React from waiting for the image to load and decode during a client-rendered View Transition update. Use `loading="lazy"` or an `onLoad` handler to opt out of that behavior. + +--- + +## Usage {/*usage*/} + +### Displaying an image {/*displaying-an-image*/} + +Pass the image URL to `src` and a text description to `alt`: + + + +```js +export default function Profile() { + return ( + Hedy Lamarr + ); +} +``` + +```css +img { + border-radius: 50%; + object-fit: cover; +} +``` + + + +Specify `width` and `height` when you know the image dimensions so the browser can reserve space before the image loads. For a decorative image, pass `alt=""` so that screen readers ignore it. + +--- + +### Controlling image preloading during server rendering {/*controlling-image-preloading-during-server-rendering*/} + +During server rendering, React automatically generates a preload hint for an `` by default. This can let the browser start fetching the image before it encounters the `` in the rendered HTML. + +Add `loading="lazy"` or `fetchPriority="low"` to an image that should not receive this hint: + +```js +function ProductPage() { + return ( + <> + Featured product + Related product + Another product + + ); +} +``` + +In this example, React generates a preload hint only for `hero.jpg`. Depending on the server API or framework, React may render the equivalent of this element: + +```html + +``` + +React may instead provide the same hint in a `Link` response header. The other two images keep their `loading` and `fetchPriority` props in the rendered HTML, but React does not generate preload hints for them. The `loading="lazy"` prop asks the browser to defer loading an image until it approaches the viewport. The `fetchPriority="low"` prop allows the image to load immediately, but tells the browser to fetch it at a lower priority. + +React also does not automatically preload an image when it is inside a `` or `