2.1 DNS Prefetch

The dns-prefetch relation is used to indicate an origin that will be used to fetch required resources, and that the user agent SHOULD resolve as early as possible.

<link rel="dns-prefetch" href="//example.com">

2.2 Preconnect

The preconnect relation 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 latency costs of establishing a connection.

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

To initiate a preconnect, the user agent MUST run these steps:

1. Resolve the URL given by the href attribute.
   1. If that is successful, let preconnect URL be the resulting absolute URL, and otherwise abort these steps.
   2. If preconnect URL's scheme is not one of "http" or "https" then abort these steps.
2. Let origin be preconnect URL's origin.
3. Let corsAttributeState be the current state of the element's crossorigin content attribute.
4. Let credentials be a boolean value set to true.
5. If corsAttributeState is Anonymous and origin is not equal to current Document's origin, set credentials to false.
6. Attempt to obtain connection with origin and credentials.

The user agent SHOULD attempt to initiate a preconnect and 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.

The optimal number of connections per origin is dependent on the negotiated protocol, users current connectivity profile, available device resources, global connection limits, and other context specific variables. As a result, the decision for how many connections should be opened is deferred to the user agent.

2.3 Prefetch

The prefetch relationship is used to declare a resource that might be required by the next navigation, and that the user agent SHOULD fetch, such that the user agent can deliver a faster response once the resource is requested in the future.

<link rel="prefetch" href="//example.com/next-page.html" as="html" crossorigin="use-credentials">
<link rel="prefetch" href="/library.js" as="script">

• The user agent SHOULD NOT apply preprocessing on the response and MUST NOT automatically execute or apply it against the current page context.
• The as attribute is an OPTIONAL attribute that must conform to requirements defined in [PRELOAD].
• The crossorigin CORS setting attribute is an OPTIONAL attribute that indicates the CORS policy of the specified resource.

2.4 Prerender

The prerender relationship is used to declare an HTML resource that might be required by the next navigation, and that the user agent SHOULD fetch and execute, such that the user agent can deliver faster response and processing once the resource is requested in the future.

<link rel="prerender" href="//example.com/next-page.html">

The user agent MAY preprocess the HTML response by also fetching the necessary subresources and executing them (i.e. prerender the page). The decision for which prerendering steps are performed is deferred to the user agent. The user agent MAY:

• Allocate fewer CPU, GPU, or memory resources to prerendered content.
• Delay some requests until the requested HTML resource is made visible - e.g. media downloads, plugin content, and so on.
• Prevent prerendering from being initiated when there are limited resources available.
• Abandon prerendering due to high cost or resource requirements - e.g. high CPU or memory usage, expensive data access, and so on.
• Abandon prerendering due to the type or properties of the fetched content:
  • If the target exhibits non-idempotent behavior: mutations to shared local storage, XMLHttpRequest with a verb other than GET, HEAD, or OPTION, and so on.
  • If the target triggers a condition that requires user input: confirmation dialogs, authentication prompts, alerts, and so on.
• The above processing strategies are not an exhaustive list. The user agent may implement other strategies.

When prerendering a document the user agent MUST set the document's visibilityState ([PAGE-VISIBILITY]) value to prerender.

3.1 Hint probability ("pr") attribute

In addition to specifying the hint type, the application MAY indicate the expected probability that the specified resource hint will be used.

<link rel="dns-prefetch" href="//widget.com" pr="0.75">
<link rel="preconnect" href="//cdn.example.com" pr="0.42">
<link rel="prefetch" href="//example.com/next-page.html" pr="0.75">
<link rel="prerender" href="//example.com/thankyou.html" pr="0.25">

The pr attribute is a float value in the [0.0-1.0] range that MAY be used in the following cases:

• With dns-prefetch and preconnect relations to indicate probability of initiating a fetch against the specified origin, either within the current navigation context, or within the next navigation context.
• With a speculative fetch relation to indicate probability of using the specified resource within the next navigation context.

If the pr attribute is omitted for above cases, the user agent MAY assign a default probability value based on own heuristics, past navigation data, and other signals.

A hint probability of 1.0 does not guarantee that the hint will be executed by the user agent. Specified hints MAY be processed on a best effort basis by the user agent, and decision to process the hint MAY be 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, specified user preferences, and other variables. The user agent MAY decide to:

• Execute some, none, or all of the optimizations implied by the resource hint, and may also invoke additional optimizations based on its own heuristics.
• Execute a partial optimization relative to the specified hint due to resource constraints or other reasons.
  • preconnect MAY fallback to a partial handshake (DNS only, or DNS+TCP for HTTPS origins).
  • speculative fetch MAY fallback to preconnect for specified origin, or apply a custom preprocessing strategy for the target resource, and if applicable, its sub-resources: preconnect only; fetch the target resource but defer fetch of sub-resources; fetch sub-resources but delay their processing, and so on.

partial interface HTMLLinkElement {
                attribute DOMString pr;
};

3.2 Fetching the resource hint link

The resource hint link's may be specified in the document markup, MAY be provided via the HTTP Link header, and MAY be dynamically added to and removed from the document.

Link: <https://widget.com>; rel=dns-prefetch
Link: <https://example.com>; rel=preconnect
Link: <https://example.com/next-page.html>; rel=prerender;
Link: <https://example.com/logo-hires.jpg>; rel=prefetch; as=image;

<link rel="dns-prefetch" href="//widget.com" pr="0.75">
<link rel="preconnect" href="//cdn.example.com" pr="0.42">
<link rel="prerender" href="//example.com/next-page.html" pr="0.75">
<link rel="prefetch" href="//example.com/logo-hires.jpg" as="image">

var hint = document.createElement("link");
hint.rel = "prefetch";
hint.as = "html";
hint.href = "/article/part3.html";
document.head.appendChild(hint);

The appropriate times to connect to a host, or obtain the specified resource are:

• When the user agent that supports [RFC5988] processes resource hint link specified via the Link HTTP header.
• When the resource hint link's link element is inserted into a document.
• When the resource hint link is created on a link element that is already in a Document.
• When the href attribute of the link element of an resource hint link that is already in a Document is changed.

The user agent MAY delay the fetch of speculative fetch to minimize resource contention for the current navigation context.

The decision to cancel a preconnect or speculative fetch is deferred to the user agent, which MAY use local context and other signals to determine if and when the optimization should be aborted:

• The user agent SHOULD abort the request if the href attribute on the link element of an resource hint link is removed, or its value is set to an empty string.
• The user agent SHOULD allow the requests initiated via the resource hint link to continue across navigations. However, the user agent MAY cancel these requests once it determines that they are not required by the new destination - see 4.4 Reactive resource prefetching (prefetch).

Resource fetches that may be required for the next navigation can negatively impact the performance of the current navigation context due to additional contention for the CPU, GPU, memory, and network resources. To address this, the user agent SHOULD implement logic to reduce and eliminate such contention:

• Resource fetches required for the next navigation SHOULD have lower relative priority and SHOULD NOT block or interfere with resource fetches required by the current navigation context.
• The optimal time to initiate a resource fetch required for the next navigation is dependent on the negotiated transport protocol, users current connectivity profile, available device resources, and other context specific variables. The user agent is left to determine the optimal time at which to initiate the fetch - e.g. the user agent MAY decide to wait until all other downloads are finished, or MAY choose to pipeline requests with low priority if the negotiated protocol supports the necessary primitives. Alternatively, the user agent MAY opt-out from initiating the fetch due to resource constraints, user preferences, or other factors.

3.3 Load and error events

The user agent MUST NOT delay the load event of the document due to outstanding preconnect or speculative fetch initiated requests.

The decision on whether a resource hint is executed, and if so, whether full or partial processing is applied is deferred to the user agent. As a result, element-level load and error JavaScripts events are not guaranteed to fire, and if they do, do not guarantee that full processing was applied. However, the user agent SHOULD fire the appropriate load and error events when possible, to allow the application to track which hints were executed and when.

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 redirect services for analytics, malware protection, 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 (without revealing any private information) in parallel with the processing of the redirect - this masks the redirect latency and reduces navigation time to final destination.

4.3 Speculative resource prefetching (prefetch)

The prefetch 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.

To achieve the above behavior the application can specify one or more prefetch relations and optionally specify the probability (via pr attribute) of each resource being used.

4.4 Reactive resource prefetching (prefetch)

The prefetch can be used to implement a "reactive prefetch strategy" that leverages the knowledge of where the user is heading next and enables the application to begin prefetching critical resources in parallel with the navigation request.

To achieve the above behavior the application can listen for click, or other user and application generated events, and dynamically insert relevant prefetch relations for critical resources required by the next navigation. In turn, the user agent can fetch the hinted resources in parallel with the navigation request, making the critical resources available sooner.

The enabling feature of this strategy is that requests initiated via prefetch relation may be allowed to persist across navigations.

4.5 Prerendering (prerender)

The prerender hint can be used to prerender the destination page, enabling an instant navigation experience once the user triggers the navigation.

To deliver an instant navigation experience the application can specify one or more prerender relations, each of which points to a destination page (an HTML resource). In turn, the user agent may fetch and process the HTML document, fetch its subresources, and perform other work to deliver an instant navigation - i.e. "prerender" the page.

Finally, because prerendering may require a lot of resources, the application can specify the probability (via pr attribute) of each target to help the user agent deliver the best user experience.