Reduce cross-origin startup time
A page loads fonts, scripts, or other assets from another origin and connection setup contributes to latency.
Next.js 16+ · Function
preconnect
Preconnect is a resource hint that begins connecting to an origin before its resources are requested. In Next.js App Router client components, use ReactDOM.preconnect to emit the hint.
How it works
In a client component, ReactDOM.preconnect emits a resource hint that asks the browser to establish an early connection to the specified origin. The optional crossOrigin setting controls whether the generated link includes cross-origin credentials behavior. For Google Fonts, Next.js may add this hint automatically, so manual use is mainly for other origins or explicit control.
Syntax
ReactDOM.preconnect(href: string, options?: { crossOrigin?: string })Parameters
| Name | Type | Description |
|---|---|---|
href | string | The origin to connect to early. |
options | { crossOrigin?: string } | Optional settings; the documented property is crossOrigin, a string controlling cross-origin behavior. |
Returns
Emits a preconnect resource hint represented as a <link rel="preconnect"> element; the documentation does not specify a return value.
Key points
- Preconnect reduces connection setup delay by starting communication with an origin before the browser needs its resource.
- The React DOM API takes a required origin string and an optional object containing
crossOrigin. - The equivalent HTML output is a link element whose relationship is
preconnect, with an optionalcrossoriginattribute. - For a manually declared font hint, target the Google Fonts domain rather than the page's own origin.
Common mistakes
- Do not add a duplicate Google Fonts preconnect unnecessarily: Next.js automatically supplies that hint for supported Google Fonts usage.
- DNS prefetch is an optional fallback for browsers that do not support preconnect; it must be a separate hint.
Example: Preconnect to a font origin
import ReactDOM from 'react-dom'
export function PreloadResources() {
ReactDOM.preconnect('https://fonts.gstatic.com', {
crossOrigin: 'anonymous',
})
return null
}Call ReactDOM.preconnect from a client component to emit a preconnect hint for an origin before its resources are requested.
When to use it
Prepare a third-party origin
An application uses a third-party origin that is not covered by Next.js's automatic Google Fonts behavior.
Declare an HTML preconnect link
A manually authored document needs the HTML form of the browser resource hint.
Interview questions
QWhat does preconnect do?
Preconnect is a resource hint that proactively starts a connection to an origin. In the App Router documentation, the React API is ReactDOM.preconnect(href, options?), and it produces a <link rel="preconnect"> hint.
Follow-up: How would you express the same hint in HTML? Use <link rel="preconnect" href="..." crossorigin />, with the cross-origin attribute when appropriate.
QWhat are the signature and options for ReactDOM.preconnect?
The required argument is the target origin as a string. The optional options object can contain crossOrigin, which controls the cross-origin mode of the generated hint.
Follow-up: What happens if the target is not cross-origin? The hint can still identify the origin, but crossOrigin should match how the eventual resource request is made.
QWhen is manual preconnect useful in Next.js?
Google Fonts commonly benefits from preconnect because the browser can begin connecting before font resources are requested. Next.js automatically adds the Google Fonts preconnect hint in versions after 12.0.1, so manually adding another one can be redundant.
Follow-up: What fallback can support older browsers? Add a separate dns-prefetch link; the documentation says this is optional rather than required.
Related
ReactDOM.preloadReactDOM.prefetchDNS<link rel="preconnect">crossOriginGoogle Fonts