2.1 Preconnect

The preconnect hint is used to indicate an origin that will be used to fetch required resources. Initiating an early connection, which includes the DNS lookup, TCP handshake, and optional TLS negotiation, allows the user agent to mask the high costs of connection establishment latency.

<link rel="preconnect" href="//example.com">
<link rel="preconnect" href="//cdn.example.com">

The optimal number of connections per origin is dependent on the negotiated protocol, users current connectivity profile, available device resources, and other context specific variables. As a result, this decision is deferred to the user agent, which is in the best position to determine the optimal number.

The user agent should perform the full connection handshake (DNS+TCP for HTTP, and DNS+TCP+TLS for HTTPS origins) whenever possible, but is allowed to elect to perform a partial handshake (DNS only for HTTP, and DNS or DNS+TCP for HTTPS origins), or skip it entirely, due to resource constraints or other reasons.

2.2 Preload

The preload hint is used to indicate the URL of a resource that should be fetched by the user agent to improve page performance: initiate an early fetch to mask request latency and make it available sooner to the application, or fetch a resource that may be required by the next user action or navigation such that it can deliver an instant response once the resource is requested.

<!-- fetch immediately + preprocess if possible -->
<link rel="preload" href="/assets/logo-small.jpeg" as="image" media="screen and (max-width: 640px)">

<!-- fetch immediately + do not preprocess -->
<link rel="preload" href="/components/widget.html" as="html" loadpolicy="inert">

<!-- low-priority fetch + preprocess if possible -->
<link rel="preload" href="//example.com/next-page.html" as="html" loadpolicy="next">

<!-- low-priority fetch + do not preprocess -->
<link rel="preload" href="//example.com/next-component.html" as="html" loadpolicy="next inert">

<link rel="preload" href="/assets/font.woff" as="font">
<link rel="preload" href="/assets/logo.webp" as="image">
<link rel="preload" href="//example.com/widget">

<link rel="preload" href="/assets/font.woff" as="font" loadpolicy="next">
<link rel="preload" href="/assets/logo.webp" as="image" loadpolicy="next inert">
<link rel="preload" href="//example.com/widget">

3.1 Required vs speculative hints

In addition to specifying the hint type, its fetch parameters, and the resource URL, the developer can communicate the expected probability that the resource will be used in the current or next navigation context.

<link rel="preconnect" href="//sub.example.com" pr="0.22">
<link rel="preload" href="//example.com/application.js" pr="0.75">
<link rel="preload" href="//example.com/thankyou.html">

The pr attribute is a float value in the [0.0-1.0] range:

• Required hint: a hint with probability of 1.0 that must be processed by the user agent.
• Speculative hint: a hint with probability of <1.0 or loadpolicy containing next keyword. Speculative hints should be processed by the user agent when possible.

If the pr attribute is omitted, the hint is considered to be a required hint (i.e. it has a probability of 1.0), unless the loadpolicy contains the next keyword. Speculative hints are processed on a best effort basis by the user agent based on the runtime context of the user agent — availability of CPU, GPU, memory, and networking resources — developer specified probability indicating the likelihood of that resource being used, and specified user preferences.

• The user agent may decide to execute some, none, or all of the optimizations implied by a speculative resource hint, and may also invoke additional optimizations based on its own heuristics.
• The user agent may decide to execute a partial optimization relative to the speculative hint due to resource constraints or other reasons.
  • preconnect may fallback to a partial handshake (DNS only, or DNS+TCP for HTTPS origins).
  • preload may fallback to preconnect for specified origin, or apply a custom preprocessing strategy for the target resource, and if applicable, its subresources: preconnect only; fetch the target resource but defer fetch of subresources; fetch subresources but delay their processing, and so on.
• The user agent may decide to not cancel outstanding fetches initiated via a required or speculative hint when a new navigation is invoked - e.g. if the navigation is to the same origin, the resource may be required by the next page. However, the user agent may cancel these requests once it determines that they are not required by the new destination.

3.2 Hint execution

The user agent must not delay the load event of the document unless the hint-initiated fetch is matched with a matching request that blocks the load event of the document.

Once the attempt to obtain the hint-initiated resource is complete, the user agent must, if the fetch was successful, queue a task to fire a simple event named load at the link element, or, if the fetch failed to complete for any reason, queue a task to fire a simple event named error at the link element.

• If the user agent is executing a required hint, then the load event on the link element is an indicator that the hint was processed to completion.
• If the user agent is executing a speculative hint, then the load event on the link element is an indicator that the user agent has performed full or partial processing on the hint (see 3.1 Required vs speculative hints).

<script>
function hintLoaded() { ... }
function hintError()  { ... }

var hint = document.createElement("link");
hint.setAttribute("rel", "preload");
hint.setAttribute("as", "image");
hint.setAttribute("href", "/image.jpg");
document.getElementsByTagName("head")[0].appendChild(hint);

// listen for load/error events
hint.addEventListener("load", function() { hintLoaded() })
hint.addEventListener("error", function() { hintError() })
</script>

<!-- listen for load/error events -->
<link rel="preload" href="app.js" as="script" onload="hintLoaded()" onerror="hintError()">

3.3 Dynamic scheduling

In addition to the hints specified in the document markup, the application may have runtime resource hints based on user context or other signals. The user agent should process dynamically inserted resource hints in addition to and in the same way as document specified hints.

// insert new preload hint
var hint = document.createElement("link");
hint.setAttribute("rel", "preload");
hint.setAttribute("loadpolicy", "next");
hint.setAttribute("href", "/article/part3.html");
document.getElementsByTagName("head")[0].appendChild(hint);

// cancel preload
document.getElementsByTagName("head")[0].removeChild(hint);

The removal of the hint from the document must cancel the optimization if it is being processed and prevent it from executing if it has not yet been invoked.

3.4 Interoperability with HTTP Link header

The user agent should process resource hints specified via the Link HTTP header [RFC5988].

Link: <https://example.com>; rel=preconnect
Link: <https://example.com/font.woff>; rel=preload; as=font
Link: <https://example.com/article/part2.html>; rel=preload
Link: <https://example.com/logo-hires.jpg>; rel=preload; as=image; media=min-resolution:2dppx

The application may provide one or more of the same type of hint via multiple HTTP headers or via a comma separated list. The user agent should process such hints in addition to and in the same way as document specified and dynamically scheduled resource hints.

3.5 Matching hint responses with requests

Resources fetched via preload are retained by the user agent until they are fetched with a matching request. The user agent may decide to discard the retained response due to resource constraints, a timeout (recommended, at least 300 seconds), or other reasons.

4.1 Dynamic request URL (preconnect)

The full resource URL may not be known until the page is being constructed by the user agent - e.g. conditional loading logic, UA adaptation, etc. However, the origin from which one or more of these resources will be fetched is often known ahead of time by the developer or the server generating the response. In such cases, a preconnect hint can be used to initiate an early connection handshake such that when the resource URL is determined, the user agent can dispatch the request without first blocking on connection negotiation.

4.2 Anonymizing redirect (preconnect)

Many sites rely on redirects for analytics and to anonymize the referrer before sending the user to the final destination. Because the destination is known ahead of time, a preconnect hint can be used to initiate the connection handshake with the destination origin in parallel with the processing of the redirect. Note that this behavior requires ability to dynamically inject the hint (e.g. as part of a JavaScript handler), and for the preconnect processing to proceed across page navigations.

4.3 Early fetch of critical resources (preload)

Speculative parsers do not execute JavaScript and perform a shallow parse of CSS, which means that the fetch of resources specified within JavaScript and CSS is delayed until the document parser is able to process the resource declaration. By using a preload hint the application can declaratively specify which resources the user agent should fetch early to mask the request latency and improve page performance.

4.4 Early fetch with on-demand processing (preload)

The preload hint can be used by the application to initiate early fetch, but delay processing of the received response - e.g. fetch a CSS stylesheet and apply it at some later time, fetch a JavaScript asset and execute it later, and so on. Preload fetches do not block the document load event and allow the application to determine which resources are applied, when they are executed, and in which order.

4.5 Developer, server, and proxy-generated hints (preload)

The preload hint can be generated both by the application and an optimization proxy (e.g. a CDN) to accelerate fetch and delivery of required resources.

1. The application can specify preload hints, allowing:
   • The optimization proxy to initiate early fetch of the associated resources and place them into its cache, thus reducing or eliminating the latency of retrieving resources from the origin.
   • The user agent to initiate early fetch of required resources - see example above.
2. The optimization proxy can specify preload hints on behalf of the application:
   • The proxy can observe and infer required resources based on past request patterns, allowing it to automate generation of relevant preload hints to improve performance.
   • The proxy can deliver inferred preload hints to the user agent while it is blocked on the response from the origin, allowing the user agent to begin fetching required resources.

Many optimization proxies already implement the "early flush" strategy where references to required resources are delivered to the user agent while the proxy is blocked on the response from the origin. Today, this is typically done by synthesizing a document header that contains XHR, image, and object requests. However, in practice, these implementations often result in prioritization conflicts with requests initiated by speculative and document parsers, or worse, result in delayed or double downloads due to missing context information. The preload hint addresses these problems by providing a declarative hint that communicates both the URL and the context of the resource.

4.6 Speculative fetching (preload)

The preload hint can be used to implement a prefetch strategy that leverages app-specific knowledge about the next navigation based on content, structure, analytics, or other signals - e.g. high-likelihood search results, paginated content or step-driven flows, aggregated analytics or per-user behavior, and so on.

For example, an image gallery may have knowledge about the likelihood of the next photo or page that may be requested by the user. To provide an improved experience the application can ask the user agent to begin fetching required resources (individual photos, critical resources, or the full page) before the next navigation is triggered.

Alternatively, instead of anticipating user activity, the application can react to user input and dynamically schedule preload requests based on its knowledge of resources that will be required by the next navigation target - i.e. the application may capture a click event and provide preload hints to the user agent before the current page is unloaded.