React Reference ยท react-dom Resource and Form APIs
React preconnect() function
Reference for react-dom preconnect(): warm up the DNS, TCP and TLS connection to a server you will request from soon, with the crossOrigin option explained.
preconnect(href, options) tells the browser to open a connection to a server before you actually request anything from it. Opening a connection to a new origin takes several round trips (DNS lookup, TCP handshake, TLS negotiation). Doing that work early removes it from the critical path of the first real request, such as an image from a CDN, a font host or your API.
React renders the call as <link rel="preconnect" href="..."> in the head, deduplicates identical calls, and on the server emits the hint as early as the stream allows. It transfers no content: only the connection is prepared.
import { preconnect } from 'react-dom'; preconnect('https://cdn.example.com'); preconnect('https://fonts.example.com', { crossOrigin: 'anonymous' });
Try it
You get two links for the same address. Browsers keep separate connection pools for requests with and without CORS credentials mode, so a fetch, font or module request (which use crossorigin) cannot reuse a connection warmed without it, and the reverse.
Four calls give three links. The identical pair collapses, but a URL with a path counts as a different string even though it points to the same server, so pass the bare origin.
Syntax
preconnect(href) preconnect(href, options)
function preconnect( href: string, options?: { crossOrigin?: 'anonymous' | 'use-credentials' | ''; } ): void;
| Name | Description |
|---|---|
href |
The server to connect to. Use just the origin, such as https://cdn.example.com. Must be a non-empty string. |
options.crossOrigin |
Match the CORS mode of the requests you will make. Use 'anonymous' (or '') for fonts, fetch() and module scripts; 'use-credentials' for credentialed CORS requests. Leave it out for ordinary <img>, classic <script> and <link rel="stylesheet"> loads. |
Returns: nothing (undefined).
Errors / edge cases: an empty or non-string href logs a development error and does nothing. Passing an options object is optional.
Usage notes
- Pass the origin. Anything after the host (path, query) is ignored by the browser but defeats deduplication, so you may end up with several links for one server.
- Match
crossOriginto the real request. A connection opened withoutcrossoriginis not used for a CORS font request. When you load both kinds from one host, preconnect twice, as in the first example. - Use it sparingly. Each warmed connection costs memory, battery and a server socket. Pick the two or three origins that matter most to the first screen; browsers may close an unused connection after a short time.
- Cheaper alternative:
prefetchDNSresolves only the domain name. Choose it when you are not sure you will use the host. - Does not apply to your own origin. The connection already exists.
- Not a fetch. It moves no data. To start downloading a file, use
preloadtoo. - Where: in a component body (during render), in an event handler such as hover, or at the top of a client entry file. All work; earlier is better.