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.
- Latest release: https://github.com/filamentgroup/loadCSS/releases
- NPM: https://www.npmjs.com/package/fg-loadcss
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 thebefore
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 anid
attribute to yourscript
.
media
: You can optionally pass a string to the media argument to set themedia=""
of the stylesheet - the default value isall
.
onload
Using with 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!