React Reference ยท react-dom Resource and Form APIs
React preinit() function
Reference for react-dom preinit(): fetch and apply a stylesheet or run a script as soon as possible, with the precedence option and how it differs from preload.
preinit(href, options) does more than preload: it fetches a stylesheet or a script and uses it right away. A stylesheet is inserted into the document head and starts applying; a script is added as an async script and runs when it arrives. Both are deduplicated, so calling preinit for the same file from ten components still loads it once.
Reach for it when you know a file will be needed but the component that needs it is not on the page yet, or when you want a resource requested during server rendering at the earliest possible moment.
import { preinit } from 'react-dom'; preinit('/css/charts.css', { as: 'style', precedence: 'default' }); preinit('/js/analytics.js', { as: 'script' });
Try it
The badge is teal because the stylesheet was inserted and applied by the call, with no <link> in your JSX.
Here precedence was left out, and React treated the stylesheet as "default" precedence.
Syntax
preinit(href, options)
function preinit( href: string, options: { as: 'style' | 'script'; precedence?: string; crossOrigin?: 'anonymous' | 'use-credentials' | ''; integrity?: string; nonce?: string; fetchPriority?: 'high' | 'low' | 'auto'; } ): void;
| Name | Description |
|---|---|
href |
URL of the stylesheet or script. |
options.as |
Required. 'style' or 'script'. Other kinds of resource use preload. |
options.precedence |
Styles only. Names the group the stylesheet belongs to; groups are kept in the order they were first seen. Defaults to "default" when omitted. See Stylesheet precedence. |
options.crossOrigin |
CORS mode: 'anonymous', 'use-credentials'. |
options.integrity |
Subresource Integrity hash. |
options.nonce |
Content Security Policy nonce. |
options.fetchPriority |
'high', 'low' or 'auto'. |
Returns: nothing (undefined).
Errors / edge cases: in development React logs a console error when options or options.as is invalid (for example as: 'font'), or when href is empty. Nothing is inserted in that case.
Usage notes
- Preload versus preinit.
preloadonly downloads.preinitalso applies the stylesheet or executes the script. Preinit a script only if it is safe to run immediately and independent of the rest of the page; it is added asasync, so ordering relative to other scripts is not guaranteed. - Stylesheets block rendering, scripts don't. A stylesheet inserted this way is render-blocking like any
<link rel="stylesheet">. Do not preinit large or unneeded CSS. - Dedup with JSX. If a component also renders
<link rel="stylesheet" href="same" precedence="default" />, React treats them as one resource. - Call it early. During render of a parent, in an event handler for "about to need it" moments (hover on a menu), or at the module top level of a client entry. Calling it in an effect works, but is later than necessary.
- Server rendering: with streaming APIs React emits the matching tags in the document head, so the browser starts the download before your JavaScript has loaded.
- Not for JavaScript modules. Use
preinitModulefortype="module"scripts. - No unload. There is no API to remove what
preinitadded. Treat it as "this file is part of the page now".