Skip to content
Tutorials Center
My learning

Topics

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.

JSX
import { preinit } from 'react-dom';

preinit('/css/charts.css', { as: 'style', precedence: 'default' });
preinit('/js/analytics.js', { as: 'script' });

Try it

Preinit a stylesheet and a script

The badge is teal because the stylesheet was inserted and applied by the call, with no <link> in your JSX.

Preinit is deduplicated

Here precedence was left out, and React treated the stylesheet as "default" precedence.

Syntax

JSX
preinit(href, options)
TypeScript
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. preload only downloads. preinit also 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 as async, 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 preinitModule for type="module" scripts.
  • No unload. There is no API to remove what preinit added. Treat it as "this file is part of the page now".