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.
import { preload } from 'react-dom'; function Hero() { preload('/fonts/display.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' }); return <h1>Welcome</h1>; }
Try it
However often you hover or click, the head keeps exactly one link for the same href and as.
Syntax
preload(href, options)
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,
typeorasthan the preload, the browser cannot reuse the cached copy and downloads the file twice. For fonts, always setcrossOrigin: 'anonymous'. - Deduplication: calls with the same
hrefandasproduce 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, usepreloadModule. - 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
renderToPipeableStreamand similar, React emits the hints near the top of the stream, and frameworks can forward them as HTTPLinkheaders. - Plain
<link rel="preload">rendered in JSX also works, but the function is deduplicated and can be called from anywhere, not only from markup.