Skip to content
Tutorials Center
My learning

Topics

React Reference ยท react-dom Resource and Form APIs

React preload() function

Reference for react-dom preload(): tell the browser to start fetching a font, image, stylesheet, script or other file before it is used, with all options.

preload(href, options) asks the browser to start downloading a file you know you will need soon, such as a font, an image, a stylesheet or a JSON response. The file is fetched and kept in the browser cache, but it is not applied or executed. When your page later uses it, the bytes are already there.

React turns the call into a <link rel="preload"> element in the document head (and into a hint in the HTML or Link header when you render on the server) and removes duplicates for you. You can call it during render, in an event handler or in an effect, from any component.

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

function Hero() {
  preload('/fonts/display.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' });
  return <h1>Welcome</h1>;
}

Try it

What preload puts in the head
Preload on hover, deduplicated

However often you hover or click, the head keeps exactly one link for the same href and as.

Syntax

JSX
preload(href, options)
TypeScript
function preload(
  href: string,
  options: {
    as: 'audio' | 'document' | 'embed' | 'fetch' | 'font' | 'image' | 'object' | 'script' | 'style' | 'track' | 'video' | 'worker';
    crossOrigin?: 'anonymous' | 'use-credentials' | '';
    referrerPolicy?: string;
    integrity?: string;
    type?: string;
    nonce?: string;
    fetchPriority?: 'high' | 'low' | 'auto';
    imageSrcSet?: string;
    imageSizes?: string;
    media?: string;
  }
): void;
Name Description
href URL of the resource. Must be a non-empty string. Absolute and relative URLs both work.
options.as Required. What kind of resource it is. The browser uses it to choose the right priority, headers and cache slot.
options.crossOrigin CORS mode. Fonts always need 'anonymous', even from your own origin.
options.type MIME type, such as font/woff2, so browsers that cannot use the format skip the download.
options.integrity Subresource Integrity hash to verify the file.
options.fetchPriority 'high', 'low' or 'auto'; a hint about importance.
options.imageSrcSet, options.imageSizes For responsive images: preload the candidate that the real <img srcset sizes> would pick.
options.media A media query; the file is only fetched when it matches.
options.referrerPolicy, options.nonce Passed through to the <link>.

Returns: nothing (undefined).

Errors / edge cases: in development React logs a console error when options or options.as is missing or href is not a non-empty string, and the call does nothing.

Usage notes

  • Match the real request. If the later request uses different CORS settings, type or as than the preload, the browser cannot reuse the cached copy and downloads the file twice. For fonts, always set crossOrigin: 'anonymous'.
  • Deduplication: calls with the same href and as produce one link, no matter how many components call it.
  • Preload does not run anything. To also apply a stylesheet or execute a script, use preinit. To fetch a module, use preloadModule.
  • Don't over-preload. Preloaded files compete with everything else for bandwidth. Reserve it for assets that are needed soon but discovered late: fonts used by CSS, hero images chosen by JavaScript, data for the next screen. A preloaded file that is not used within a few seconds triggers a browser warning.
  • Where to call it: during render is fine and the common choice. Event handlers suit "warm up on hover or focus".
  • Server rendering: in renderToPipeableStream and similar, React emits the hints near the top of the stream, and frameworks can forward them as HTTP Link headers.
  • Plain <link rel="preload"> rendered in JSX also works, but the function is deduplicated and can be called from anywhere, not only from markup.