W3cubDocs

/HTML

Preloading content

The preload value of the <link> element's rel attribute allows you to write declarative fetch requests in your HTML <head>, specifying resources that your pages will need very soon after loading, which you therefore want to start preloading early in the lifecycle of a page load, before the browser's main rendering machinery kicks in. This ensures that they are made available earlier and are less likely to block the page's first render, leading to performance improvements. This article provides a basic guide to how preload works.

The basics

You most commonly use the humble <link> element when loading a CSS file to style your page with:

<link rel="stylesheet" href="styles/main.css">

Here however, we will use a rel value of preload, which turns the <link> element into a preloader for pretty much any resource we want. At a basic level, you also need to specify the path to the resource to be preloaded in the href attribute, and the type of resource you are preloading in the as attribute.

A simple example might look like this (see our JS and CSS example source, and also live):

<head>
  <meta charset="utf-8">
  <title>JS and CSS preload example</title>

  <link rel="preload" href="style.css" as="style">
  <link rel="preload" href="main.js" as="script">

  <link rel="stylesheet" href="style.css">
</head>

<body>
  <h1>bouncing balls</h1>
  <canvas></canvas>

  <script src="main.js"></script>
</body>

Here we are preloading our CSS and JavaScript files so they will be available as soon as they are required during the rendering of the page later on. This example is somewhat trivial, but the benefits can be seen much more clearly, the later in the rendering the resources are discovered and the larger they are. For example, what about resources that are pointed to from inside a CSS file like fonts or images, or larger images and video files?

preload has other advantages too. Using as to specify the type of content to be preloaded allows the browser to:

Prioritize resource loading more accurately.
Match future requests, reusing the same resource if appropriate.
Apply the correct content security policy to the resource.
Set the correct Accept request headers for it.

What types of content can be preloaded?

Many different content types can be preloaded; the main available as attribute values are as follows:

audio: Audio file.
document: An HTML document intended to be embedded inside a <frame> or <iframe>.
embed: A resource to be embedded inside an <embed> element.
fetch: Resource to be accessed by a fetch or XHR request, such as an ArrayBuffer or JSON file.
font: Font file.
image: Image file.
object: A resource to be embedded inside an <embed> element.
script: JavaScript file.
style: Stylesheet.
track: WebVTT file.
worker: A JavaScript web worker or shared worker.
video: Video file.

Note: You can read a bit more detail about these values and the web features they are expected to be consumed by in the Preload spec — see link element extensions. Also note that the full list of values the as attribute can take is governed by the definitions in the Fetch spec — see request destinations.

Including a MIME type

<link> elements can accept a type attribute, which contains the MIME type of the resource the element is pointing to. This is especially useful when preloading resources — the browser will use the type attribute value to work out whether it supports that resource, and will only start downloading it if this is the case, ignoring it if not.

You can see an example of this in our video example (see the full source code, and also the live version):

<head>
  <meta charset="utf-8">
  <title>Video preload example</title>

  <link rel="preload" href="sintel-short.mp4" as="video" type="video/mp4">
</head>
<body>
  <video controls>
    <source src="sintel-short.mp4" type="video/mp4">
    <source src="sintel-short.webm" type="video/webm">
    <p>Your browser doesn't support HTML5 video. Here is a <a href="sintel-short.mp4">link to the video</a> instead.</p>
  </video>
</body>

So in this case, browsers that support MP4s will preload and use the MP4, making the video player hopefully smoother/more responsive for users. Browsers that don't support the MP4 can still load the WebM version, but don't get the advantages of preloading. This shows how preloading content can be combined with the philosophy of progressive enhancement.

Cross-origin fetches

If you've got your sites' CORS settings worked out properly, you can successfully preload cross-origin resources as long as you set a crossorigin attribute on your <link> element.

One interesting case in which this applies even if the fetch is not cross-origin is font files. Because of various reasons, these have to be fetched using anonymous mode CORS (see Font fetching requirements if you are interested in all the details).

Let's use this case as an example, firstly because font loading is a really good use case for preloading, and secondly, because it is easier than setting up a cross-origin request example. You can see the full example source code on GitHub (also see it live):

<head>
  <meta charset="utf-8">
  <title>Web font example</title>

  <link rel="preload" href="fonts/cicle_fina-webfont.eot" as="font" type="application/vnd.ms-fontobject" crossorigin="anonymous">
  <link rel="preload" href="fonts/cicle_fina-webfont.woff2" as="font" type="font/woff2" crossorigin="anonymous">
  <link rel="preload" href="fonts/cicle_fina-webfont.woff" as="font" type="font/woff" crossorigin="anonymous">
  <link rel="preload" href="fonts/cicle_fina-webfont.ttf" as="font" type="font/ttf" crossorigin="anonymous">
  <link rel="preload" href="fonts/cicle_fina-webfont.svg" as="font" type="image/svg+xml" crossorigin="anonymous">

  <link rel="preload" href="fonts/zantroke-webfont.eot" as="font" type="application/vnd.ms-fontobject" crossorigin="anonymous">
  <link rel="preload" href="fonts/zantroke-webfont.woff2" as="font" type="font/woff2" crossorigin="anonymous">
  <link rel="preload" href="fonts/zantroke-webfont.woff" as="font" type="font/woff" crossorigin="anonymous">
  <link rel="preload" href="fonts/zantroke-webfont.ttf" as="font" type="font/ttf" crossorigin="anonymous">
  <link rel="preload" href="fonts/zantroke-webfont.svg" as="font" type="image/svg+xml" crossorigin="anonymous">

  <link href="style.css" rel="stylesheet" type="text/css">
</head>
<body>
  ...
</body>

You'll see here that not only are we providing the MIME type hints in the type attributes, but we are also providing the crossorigin attribute to handle the CORS issue.

Including media

One nice feature of <link> elements is their ability to accept media attributes. These can accept media types or full-blown media queries, allowing you to do responsive preloading!

Let's look at a very simple example (see it on GitHub — source code, live example):

<head>
  <meta charset="utf-8">
  <title>Responsive preload example</title>

  <link rel="preload" href="bg-image-narrow.png" as="image" media="(max-width: 600px)">
  <link rel="preload" href="bg-image-wide.png" as="image" media="(min-width: 601px)">

  <link rel="stylesheet" href="main.css">
</head>
<body>
  <header>
    <h1>My site</h1>
  </header>

  <script>
    var mediaQueryList = window.matchMedia("(max-width: 600px)");
    var header = document.querySelector('header');

    if(mediaQueryList.matches) {
      header.style.backgroundImage = 'url(bg-image-narrow.png)';
    } else {
      header.style.backgroundImage = 'url(bg-image-wide.png)';
    }
  </script>
</body>

You'll see that we are including media attributes on our <link> elements so that a narrow image is preloaded if the user is on a narrow screen device, and a wider image is loaded if they are on a wider screen device. We still need to attach the correct image to the header depending on the result — we use Window.matchMedia / MediaQueryList to do this (see Testing media queries for more information on this).

This makes it much more likely that the font will be available by the time the page render is complete, cutting down on FOUT (flash of unstyled text) issues.

Note that this doesn't have to be limited to images, or even files of the same type — think big! You could perhaps preload then display a simple SVG diagram if the user is on a narrow screen where bandwidth and CPU is potentially more limited, or preload a complex chunk of JavaScript then use it to render an interactive 3D model if the user's resources are more plentiful.

Scripting and preloads

Another nice thing about these preloads is that you can execute them completely with script if desired. For example, here we are creating a HTMLLinkElement instance, then attaching it to the DOM:

var preloadLink = document.createElement("link");
preloadLink.href = "myscript.js";
preloadLink.rel = "preload";
preloadLink.as = "script";
document.head.appendChild(preloadLink);

This means that the browser will preload the JavaScript file, but not actually use it yet.

To use it, you could do this when desired:

var preloadedScript = document.createElement("script");
preloadedScript.src = "myscript.js";
document.body.appendChild(preloadedScript);

This is useful when you want to preload a script, but then defer executing it until exactly when you need it.

Other resource preloading mechanisms

Other preloading features exist, but none are quite as fit for purpose as <link rel="preload">:

<link rel="prefetch"> has been supported in browsers for a long time, but it is intended for prefetching resources that will be used in the next navigation/page load (e.g. when you go to the next page). This is fine, but isn't useful for the current page! In addition, browsers will give prefetch resources a lower priority than preload ones — the current page is more important than the next one. See Link prefetching FAQ for more details.
<link rel="subresource"> was supported in Chrome a while ago, and was intended to tackle preloading resources for the current navigation/page load, but it had a problem — there was no way to work out a priority for fetching the items (as didn't exist back then), so they all ended up being fetched with fairly low priority, which didn't help the situation.
There are a number of script-based resource loaders out there, but they don't have any power over the browser's fetch prioritization queue, and are subject to much the same performance problems.

Specifications

Specification	Status	Comment
Preload The definition of 'preload' in that specification.	Candidate Recommendation	Further details of `preload`.
HTML Living Standard The definition of 'rel=preload' in that specification.	Living Standard	Definition of `rel=preload`.

Browser compatibilityUpdate compatibility data on GitHub

	Desktop
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari
Basic support	50	?	56 — 57 56 — 57 Disabled due to various web compatibility issues (e.g. bug 1405761). An improved version that works for non-cacheable resources is expected to land soon.	?	?	?

	Mobile
	Android webview	Chrome for Android	Edge Mobile	Firefox for Android	Opera for Android	iOS Safari	Samsung Internet
Basic support	50	50	?	56 — 57 56 — 57 Disabled due to various web compatibility issues (e.g. bug 1405761). An improved version that works for non-cacheable resources is expected to land soon.	?	?	5.0