Skip to content
Tutorials Center
My learning

Topics

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.

JSX
function Map({ center }) {
  return (
    <>
      <script async src="https://maps.example.com/sdk.js" />
      <div id="map" data-center={center} />
    </>
  );
}

Try it

Three components, one script element
A load handler makes the script inert

Syntax

JSX
<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 src does 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 sets onload on 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() and preinitModule() functions from react-dom start loading a script from code, with the same deduplication, without rendering anything.