fg-loadcss

loadCSS

A function for loading CSS asynchronously [c]2016 @scottjehl, Filament Group, Inc. Licensed MIT

Why loadCSS?

Referencing CSS files with link[rel=stylesheet] or @import will cause most browsers to delay page rendering while the stylesheet loads. This is desirable in many cases, but when loading stylesheets that are not critical to the initial rendering of a page, loadCSS (and upcoming web standards mentioned below) allows you to load stylesheets asynchronously, so they don’t block page rendering.

Basic Usage

With the loadCSS function referenced in your page, simply call the loadCSS function and pass it a stylesheet URL:

loadCSS( "path/to/mystylesheet.css" );

The code above will insert a new CSS stylesheet link after the last stylesheet or script that loadCSS finds in the page, and the function will return a reference to that link element, should you want to use it later in your script. Multiple calls to loadCSS will reference CSS files in the order they are called, but keep in mind that they may finish loading in a different order than they were called depending on network conditions.

Recommended Usage Pattern

Browsers are beginning to support a standard markup pattern for loading CSS (and other file types) asynchronously: <link rel="preload"> (W3C Spec). We recommend using this markup pattern to reference any CSS files that should be loaded asynchronously, and using loadCSS to polyfill support browsers that don't yet support this new feature.

The markup for referencing your CSS file looks like this:

<link rel="preload" href="path/to/mystylesheet.css" as="style" onload="this.rel='stylesheet'">
<noscript><link rel="stylesheet" href="path/to/mystylesheet.css"></noscript>

Since rel=preload does not apply the CSS on its own (it merely fetches it), there is an onload handler on the link that will do that for us as soon as the CSS finishes loading. Since this step requires JavaScript, you may want to include an ordinary reference to your CSS file as well, using a noscript element to ensure it only applies in non-JavaScript settings.

With that markup in the head of your page, include the loadCSS script, as well as the loadCSS rel=preload polyfill script in your page (inline to run right away, or in an external file if the CSS is low-priority).

No further configuration is needed, as these scripts will automatically detect if the browsers supports rel=preload, and if it does not, they will find CSS files referenced in the DOM and preload them using loadCSS. In browsers that natively support rel=preload, these scripts will do nothing, allowing the browser to load and apply the asynchronous CSS (note the onload attribute above, which is there to set the link's rel attribute to stylesheet once it finishes loading in browsers that support rel=preload).

Note: regardless of whether the browser supports rel=preload or not, your CSS file will be referenced from the same spot in the source order as the original link element. Keep this in mind, as you may want to place the link in a particular location in your head element so that the CSS loads with an expected cascade order.

You can view a demo of this rel=preload pattern here: http://filamentgroup.github.io/loadCSS/test/preload.html

Function API

If you're calling loadCSS manually (without the rel=preload pattern, the function has 3 optional arguments.

• before: By default, loadCSS attempts to inject the stylesheet link after all CSS and JS in the page. However, if you desire a more specific location in your document, such as before a particular stylesheet link, you can use the before argument to specify a particular element to use as an insertion point. Your stylesheet will be inserted before the element you specify. For example, here's how that can be done by simply applying an id attribute to your script.

... ... ```

• media: You can optionally pass a string to the media argument to set the media="" of the stylesheet - the default value is all.

Using with onload

Onload event support for link elements is spotty in some browsers, so if you need to add an onload callback, include onloadCSS function on your page and use the onloadCSS function:

var stylesheet = loadCSS( "path/to/mystylesheet.css" );
onloadCSS( stylesheet, function() {
	console.log( "Stylesheet has loaded." );
});

Browser Support

loadCSS attempts to load a css file asynchronously in any JavaScript-capable browser. However, some older browsers will block rendering while the stylesheet is loading. This table outlines css loading support and async loading support.

Browser	CSS Loads Successfully	CSS Loads without Blocking Render
Chrome Mac (latest and many recent versions)	Yes	Yes
Firefox Desktop (latest and many recent versions)	Yes	Yes
Opera Mac (latest and many recent versions)	Yes	Yes
Safari Mac (latest and many recent versions)	Yes	Yes
Safari iOS (latest and many recent versions)	Yes	Yes
Chrome Android 5.x	Yes	Yes
Chrome Android 4.x	Yes	Yes
Android Browser 2.3	Yes	No
Kindle Fire HD	Yes	Yes
Windows Phone IE 8.1	Yes	Yes
IE 11	Yes	Yes
IE 10	Yes	Yes
IE 9	Yes	Yes
IE 8	Yes	No
IE 7	Yes	No
IE 6	Yes	No

Usage Tips

We typically use loadCSS to load CSS files that are non-critical to the initial rendering of a page. See the EnhanceJS project Readme for examples of how we typically use it to improve page loading performance (note: the newest rel=preload pattern is not yet in that readme, but the concepts are the same).

Contributions and bug fixes

Both are very much appreciated - especially bug fixes. As for contributions, the goals of this project are to keep things very simple and utilitarian, so if we don't accept a feature addition, it's not necessarily because it's a bad idea. It just may not meet the goals of the project. Thanks!