Skip to content
Tutorials Center
My learning

Topics

React Reference ยท react-dom Resource and Form APIs

React preloadModule() function

Reference for react-dom preloadModule(): download an ES module and its dependencies before an import runs, using modulepreload, with options and pitfalls.

preloadModule(href, options) starts downloading an ES module so that a later import of it finishes quickly. The browser fetches the file, parses it and also fetches the modules it imports, but it does not run it. React renders the call as <link rel="modulepreload"> in the document head and deduplicates repeated calls.

Use it for code you know is coming: the chunk behind the next route, a heavy editor loaded on a button press, or a Web Worker script. For a module that should also execute immediately, use preinitModule. For classic scripts and every other file type, use preload.

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

preloadModule('/assets/editor.js', { as: 'script' });

Try it

What preloadModule adds

The ordinary module shows (default) because React leaves the as attribute out for scripts; only the worker carries it.

Warm up on hover, once

Hover or tab to the link repeatedly: the call count grows, the link count stays at 1.

Syntax

JSX
preloadModule(href)
preloadModule(href, options)
TypeScript
function preloadModule(
  href: string,
  options?: {
    as?: 'script' | 'worker' | 'sharedworker' | 'serviceworker' | 'audioworklet' | 'paintworklet';
    crossOrigin?: 'anonymous' | 'use-credentials' | '';
    integrity?: string;
    nonce?: string;
  }
): void;
Name Description
href URL of the module. Must be a non-empty string.
options.as Kind of consumer when it is not an ordinary module script, such as 'worker'. Omit it for normal import.
options.crossOrigin CORS mode used by the later import. Modules are fetched with CORS, so a cross-origin module needs a server that sends the right headers.
options.integrity Subresource Integrity hash.
options.nonce Content Security Policy nonce.

Returns: nothing (undefined).

Errors / edge cases: an empty href, or an as value that is not valid for modulepreload, logs a development error and adds nothing.

Usage notes

  • Downloads and parses, but never runs. Top-level code of the module does not execute until something imports it. That makes the hint safe for modules with side effects.
  • Dependencies are included. Unlike preload, modulepreload also fetches the static imports of the module, which is why it suits bundler chunks.
  • Dedupe with preinitModule. If the same URL was already passed to preinitModule, a later preloadModule adds nothing, because the module is already requested.
  • Use final URLs. In bundled apps, file names carry content hashes. Take the URL from your bundler's manifest rather than hard-coding it.
  • Frameworks often do this for you. Route-based code splitting tools already emit module preloads for the next navigation. Call it by hand only for things they cannot see.
  • Do not preload everything. Idle modules still use bandwidth and memory. Trigger it on likely intent (hover, focus, visibility), not on page load for every route.
  • React.lazy pairs well: call preloadModule for the chunk, then render the lazy component when needed. See lazy.