This specification defines the preload relationship of the HTML Link Element (<link>).

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the Web Performance Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-web-perf@w3.org (subscribe, archives). All comments are welcome.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 August 2014 W3C Process Document.

Table of Contents

1. Introduction

Many applications require fine-grained control over when resources are fetched, processed, and applied to the document. For example, the loading and processing of some resources may be deferred by the application to reduce resource contention and improve performance of the initial load. This behavior is typically achieved by moving resource fetching into custom resource loading logic defined by the application - i.e. resource fetches are initiated via injected elements, or via XMLHttpRequest, when particular application conditions are met.

However, there are also cases where some resources need to be fetched as early as possible, but their processing and execution logic is subject to application-specific requirements - e.g. dependency management, conditional loading, ordering guarantees, and so on. Currently, it is not possible to deliver this behavior without a performance penalty.

The preload relationship of the HTML Link Element provides a declarative fetch primitive that addresses the above use case of initiating an early fetch and separating fetching from resource execution. As such, preload relationship serves as a low-level primitive that enables applications to build custom resource loading and execution behaviors without hiding resources from the user agent and incurring delayed resource fetching penalties.

2. Preload

The preload relationship is used to declare a resource and its fetch properties. Initiating an early fetch allows the application to mask request latency and make it available sooner to the application, which can then decide when and in which order each resource is applied to the current document.

Example 1
<!-- preload a widget component -->
<link rel="preload" href="/components/widget.html" as="iframe">

<!-- preload an application script -->
<link rel="preload" href="/app/script.js" as="javascript">

<!-- preload a CSS stylesheet -->
<link rel="preload" href="/style/style.css" as="stylesheet">

<!-- preload an image asset -->
<link rel="preload" href="//example.com/image.jpg" as="image" media="screen and (max-width: 640px)">

2.1 Initializing fetch settings

The crossorigin CORS setting attribute is an OPTIONAL attribute that indicates the CORS policy of the specified resource. [HTML5]

The as attribute on a preload relationship specifies the request context used to initialize appropriate fetch settings - e.g. request priority, HTTP headers, etc. [FETCH]

Example 2
<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" as="iframe">
The resource destination context communicated via the as attribute is only used to initialize appropriate fetch settings; the communicated context is not meant to enforce security or other resource policies.

2.3 Load and error events

Once the attempt to obtain the 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.

Example 6
function preloadFinished(e) { ... }
function preloadError(e)  { ... }

<!-- listen for load and error events -->
<link rel="preload" href="app.js" as="script" onload="preloadFinished()" onerror="preloadError()">
The application can use the load event on a preload relation as an indicator that the resource has been successfully fetched and is now ready to be processed by the application - e.g. a stylesheet or script can be applied to a document, and so on, without blocking on the network.

2.4 Matching responses with requests

Resources fetched via preload relation MUST be retained by the user agent for the duration of the current navigation until they are fetched with a matching request.

For example, if a JavaScript resource is fetched via a preload relation and the response contains a no-cache directive, the fetched response is retained by the user agent and is made immediately available when fetched with a matching same navigation request at a later time - e.g. via a script tag or other means. This ensures that the user agent does not incur an unnecessary revalidation, or a duplicate download, between the initial resource fetch initiated via the preload relation and a later fetch requesting the same resource.


The concept of "matching" is not currently defined or interoperable across user agents. This should be fixed, but it is out of scope of this specification. For further discussion see this bug and chromium discussion.

A. Use cases

This section is non-normative.

A.1 Early fetch of critical resources

Speculative parsers are used by most user agents to initiate early resource fetches while the main document parser is blocked due to a blocking script. However, these speculative parsers do not execute JavaScript, and typically only perform a shallow parse of CSS, which means that the fetch of resources specified within JavaScript and CSS is delayed until the relevant document parser is able to process the resource declaration.

In effect, most resources declarations specified within JavaScript and CSS are "hidden" from the speculative parsers and incur a performance penalty. To address this, the application can use the preload relation to declaratively specify which resources the user agent must fetch early to improve page performance.

A.2 Early fetch and application defined execution

The preload relation can be used by the application to initiate early fetch of one or more resources, as well as to provide custom logic for when and how each response should be applied to the document. The application may:

The preload relation provides a low-level and content-type agnostic primitive that enables applications to build custom resource loading and execution behaviors without incurring the penalty of delayed resource loading.

For example, preload relation enables the application to provide async and defer like semantics, which are only available on script elements today, but for any content-type: applying the resource immediately after it is available provides async functionality, whereas adding some ordering logic enables defer functionality. Further, this behavior can be defined across a mix of content-types - the application is in full control over when and how each resource is applied.

By decoupling resource fetching from execution, the preload relation provides a future-proof primitive for building performant application specific resource loading strategies.

A.3 Developer, server, and proxy-initiated fetching

The preload relation can be specified by the developer, or be automatically generated by the application server or an optimization proxy (e.g. a CDN).

B. Acknowledgments

This section is non-normative.

This document reuses text from the [HTML] specification, edited by Ian Hickson, as permitted by the license of that specification.

C. References

C.1 Normative references

Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
M. Nottingham. Web Linking. October 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5988
Florian Rivoal; Tab Atkins Jr.. Media Queries Level 4. 5 June 2014. W3C Working Draft. URL: http://www.w3.org/TR/mediaqueries-4/

C.2 Informative references

Ian Hickson. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/