Preload

Preload

Use am_preload for preloading assets of any supported type.

// `as` and `mime_type` options will be automatically added for CSS, but are included here for clarity.
am_preload(
  [
    'handle'    => 'preload-styles',
    'src'       => 'css/styles.css',
    'condition' => 'global',
    'version'   => '1.0.0',
    'as'        => 'style'
    'mime_type' => 'text/css',
  ]
);

Result:

<link rel="preload" href="http://client/css/test.css?ver=1.0.0" class="wp-asset-manager preload-styles" as="style" media="all" type="text/css" />

The am_preload function patches the as and mime_type option values for common use-cases (CSS, JavaScript and WOFF2 fonts), but will throw an error if the as option is missing for any other file type.

From the spec:

The [as] attribute is necessary to guarantee correct prioritization, request matching, application of the correct Content Security Policy policy, and setting of the appropriate Accept request header.

This function will also automatically add the crossorigin attribute for fonts, which is required when preloading fonts, even if they're not actually cross-origin requests.

Responsive Images

Preloading a responsive image without telling the browser about the other candidates is usually a wasted download: the browser fetches src, then reaches the <img> tag and picks a different file. The imagesrcset and imagesizes options are the preload equivalent of an <img> tag's srcset and sizes, and let the browser pick the right candidate up front.

am_preload(
  [
    'handle'        => 'preload-hero',
    'src'           => 'images/hero.jpg',
    'imagesrcset'   => 'images/hero-480.jpg 480w, images/hero-800.jpg 800w',
    'imagesizes'    => '(max-width: 600px) 480px, 800px',
    'fetchpriority' => 'high',
  ]
);

Result:

<link rel="preload" href="http://client/images/hero.jpg" class="wp-asset-manager preload-hero" as="image" media="all" imagesrcset="images/hero-480.jpg 480w, images/hero-800.jpg 800w" imagesizes="(max-width: 600px) 480px, 800px" fetchpriority="high" />

as is set to image automatically when imagesrcset is supplied without one.

Declaring candidates as an array

imagesrcset also accepts an array keyed by descriptor, so each candidate is declared once instead of hand-assembling the string. An integer key becomes a width descriptor; a string key is used as-is, which is how pixel density candidates are declared.

am_preload(
  [
    'handle'      => 'preload-hero',
    'src'         => 'images/hero.jpg',
    'imagesrcset' => [
      480  => 'images/hero-480.jpg',
      800  => 'images/hero-800.jpg',
      1600 => 'images/hero-1600.jpg',
    ],
    'imagesizes'  => '(max-width: 600px) 480px, 800px',
  ]
);

// Densities instead of widths.
am_preload(
  [
    'handle'      => 'preload-logo',
    'src'         => 'images/logo.png',
    'imagesrcset' => [
      '1x' => 'images/logo.png',
      '2x' => 'images/logo-2x.png',
    ],
  ]
);

A plain list of URLs won't work — without keys there are no descriptors, and sequential indexes would be read as widths. That raises a _doing_it_wrong() notice and the attribute is dropped.

Notices

Each of these raises a _doing_it_wrong() notice and drops the attribute rather than printing something the browser will ignore:

• imagesizes without imagesrcset — sizes picks from the candidates in the srcset, so it has nothing to choose from.
• A fetchpriority other than auto, high, or low.
• An imagesrcset array that isn't keyed by descriptor.

Preload Options

Name	Description	Required	Default
handle	The handle for the asset	•
src	The URI for the asset	•
condition	The condition for which this asset should load		'global'
version	The asset version		'1.0.0'
as	The as attribute's value (info)	•
mime_type	The type attribute's value (info)	•
media	The media attribute value used to conditionally preload the asset		'all'
imagesrcset	Candidate images, as a string or keyed by descriptor (info)
imagesizes	The sizes the image will display at. Requires imagesrcset
fetchpriority	Fetch priority hint. One of 'auto', 'high', 'low'