Skip to content

Add an <img> API reference - #8658

Open
aurorascharff wants to merge 2 commits into
reactjs:mainfrom
aurorascharff:codex/document-img-component
Open

aurorascharff wants to merge 2 commits into
reactjs:mainfrom
aurorascharff:codex/document-img-component

Conversation

@aurorascharff

@aurorascharff aurorascharff commented Sep 15, 2026

Copy link
Copy Markdown
Collaborator

Adds an API reference for the built-in browser <img> component.

The new reference:

  • documents image-specific props and caveats
  • explains automatic image preload hints during server rendering, including opt-out behavior and how frameworks and component libraries may provide different defaults
  • documents how images participate in synchronized View Transition reveals

It also adds <img> to the React DOM components index and sidebar.

The automatic preloading behavior was introduced in react/react#27191 and discussed in react/react#34217.

@aurorascharff
aurorascharff force-pushed the codex/document-img-component branch from 802e2ce to 8b6536c Compare September 15, 2026 09:28
@aurorascharff aurorascharff changed the title Document React-specific img behavior Add an <img> API reference Sep 15, 2026
@github-actions

github-actions Bot commented Sep 15, 2026

Copy link
Copy Markdown

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

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

One Page Changed Size

The following page changed size from the code in this PR compared to its base branch:

Page Size (compressed) First Load
/[[...markdownPath]] 130.03 KB (🟡 +9 B) 245.18 KB
Details

Only the gzipped size is provided here based on an expert tip.

First Load is the size of the global bundle plus the bundle for the individual page. If a user were to show up to your website and land on a given page, the first load size represents the amount of javascript that user would need to download. If next/link is used, subsequent page loads would only need to download that page's bundle (the number in the "Size" column), since the global bundle has already been downloaded.

Any third party scripts you have added directly to your app using the <script> tag are not accounted for in this analysis

Next to the size is how much the size has increased or decreased compared with the base branch of this PR. If this percentage has increased by 10% or more, there will be a red status indicator applied, indicating that special attention should be given to this.


#### Caveats {/*caveats*/}

* Do not pass an empty string to `src`. React warns in development and omits the attribute. To render no image, omit the `<img>` or pass `null` to `src`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

worth explaining why? With an empty attribute the browser would make a request to the current page.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants