React Reference ยท react-dom Resource and Form APIs
Async scripts in React
Reference for async script elements in React 19: render them from any component, get one hoisted copy per src, and learn which props opt out of that.
A <script async src="..."> element rendered by a component is treated as a resource, not as ordinary markup. React moves it into the document <head>, adds it only once per src, and keeps it there after the component unmounts. That lets a component declare the third-party script it needs without knowing whether a sibling already loaded the same file.
The feature exists since React 19 and works in client rendering, server rendering and streaming. It applies only to scripts that have both async and src. Inline scripts and non-async scripts stay where you write them.
function Map() { return ( <section> <script async src="https://example.com/map-widget.js" /> <div id="map" /> </section> ); }
Try it
The three components render three paragraphs, but the console reports one script in <head> and none in <body>. The script address is a data: URL so the demo needs no server; the percent sign is written as %2B to produce a +.
The output has a single <script async src="/widget.js"> inside <head>, before the title. The classic script and the inline script remain in the body, in the order you wrote them.
Syntax
<script async src={url} /> <script async src={url} crossOrigin="anonymous" integrity={hash} nonce={nonce} />
| Prop | Description |
|---|---|
async |
Required. Must be present and truthy for the script to be treated as a resource. |
src |
Required string. It is the identity used to remove duplicates: two elements with the same src become one. |
crossOrigin, integrity, nonce, referrerPolicy, fetchPriority |
Optional. Passed through to the one real element. |
onLoad, onError |
Opt the element out of hoisting (see below). |
Returns: the element itself renders nothing at its place in the tree; the script appears in the head.
Usage notes
- Deduplication is by
src. Only one element exists per URL, so give every component the samecrossOrigin,integrityandnoncefor it. Do not count on a later component's different props being applied. - No cleanup. Unmounting the last component that renders the script does not remove it or stop code it already ran. Treat the script as page-level, not component-level.
- Event handlers disable the feature. An async script with
onLoadoronErroris rendered as a normal element at its position, and duplicates are not merged. On the server it is written in the body instead of the head. - Execution is the browser's job. React only places the element. It does not wait for the script, and the code may run before or after your component has rendered, so a component must not assume the script's globals exist yet.
- No hoisting for other scripts.
<script src>withoutasync, module scripts withoutasync, and inline scripts keep their place and are never merged. - Content security policy. Pass the same
noncethat your policy header uses; React copies it to the final element. - Server rendering writes the script into the
<head>of the document you render, so render the full<html>tree when you want the head output to be complete. - Prefer a bundled dependency when the code is yours. This feature is for external scripts such as maps, payment widgets or analytics.