React Reference ยท Built-in DOM Components
The React script element
Reference for the React script element: render async scripts from components, let React deduplicate them by src, and know when a script stays in place.
React 19 lets a component render a <script async src="..."> that it needs, such as an analytics snippet, a map SDK or a payment widget. React moves that element into the <head>, and when several components ask for the same src, only one script element is added. The component can describe what it depends on without coordinating with the rest of the tree.
The rules are narrow. Hoisting and deduplication apply only to scripts that are async and have a string src and have no onLoad or onError handler. Every other script (inline code, synchronous scripts, scripts with load handlers) is rendered in place as an inert element: when React creates it on the client, the browser never runs it.
function Map({ center }) { return ( <> <script async src="https://maps.example.com/sdk.js" /> <div id="map" data-center={center} /> </> ); }
Try it
Syntax
<script async src="https://example.com/sdk.js" />
| Name | Description |
|---|---|
src |
The script URL. Must be a non-empty string for hoisting. Used as the key for deduplication. |
async |
Must be true for hoisting. The script runs as soon as it is downloaded, in no guaranteed order. |
type="module" |
Module scripts work too; they are deferred by nature. |
crossOrigin, integrity, nonce, referrerPolicy, fetchPriority |
Same as in HTML. Use integrity for third-party code and nonce with a Content Security Policy. |
onLoad, onError |
If you set either, React does not hoist or deduplicate the script, and the inert in-place element never loads, so the handler never fires. |
children |
Inline code. It is not executed when React creates the element on the client. |
Returns: an HTMLScriptElement in document.head (when hoisted) or in place (otherwise).
Edge cases: a script without async, without a string src, or with a load handler is a normal element. Rendering a new script with a different src adds another script; removing a component does not remove a script that already ran.
Usage notes
- The script runs once. Deduplication means a second component asking for the same
srcdoes not run the code again. If you need to know when it is ready, check the global it defines, or wrap loading in a small promise-based helper that setsonloadon an element you create yourself. - No ordering guarantees. Two async scripts can finish in either order. If one depends on another, make a single entry script that loads both, or use modules.
- Inline scripts do not execute.
<script>{'alert(1)'}</script>rendered on the client creates a dead element. On the server it is part of the HTML and runs in the browser, but never use that for user-supplied strings. Prefer JSON in<script type="application/json">for data. - Cleanup does not unload. A script that has run cannot be un-run. Removing the component removes nothing from the page that React has hoisted.
- Security. Third-party scripts have full access to your page. Pin versions, add
integrity, and consider loading them in a sandboxed iframe. - Core Web Vitals. Async scripts compete with your own bundle. Load analytics late and give them
fetchPriority="low". - Alternatives. The
preinit()andpreinitModule()functions fromreact-domstart loading a script from code, with the same deduplication, without rendering anything.