$async can be used as a javascript function or through a HTML attribute on a script element.
$async accepts 8 arguments:
CSS loader config
CSS loader global options
CSS capture config
CSS capture global options
Javascript loader config
Javascript loader global options
Javascript capture config
Javascript capture global options
$async([/*stylesheets*/], // string, object or an array of strings or objects{/*options*/}, // object[/*capture*/], // string, object or an array of strings or objects{/*capture options*/}, // object​[/*scripts*/], // string, object or an array of strings or objects{/*options*/}, // object[/*capture*/], // string, object or an array of strings or objects{/*capture options*/} // object).then(function() { /* ready */ });
Usage through a HTML attribute.
<script async src="js/async-iife.js" data-c='[[/*stylesheets*/], // string, object or an array of strings or objects{/*options*/}, // object[/*capture*/], // string, object or an array of strings or objects{/*capture options*/}, // object​[/*scripts*/], // string, object or an array of strings or objects{/*options*/}, // object[/*capture*/], // string, object or an array of strings or objects{/*capture options*/} // object]'></script>
$async is chainable and provides an API.
// alternative load method for chaining when using the API module$async.load(/*...*/) // CSS loader that accepts 8 arguments.js(/**/) // javascript loader only.then(function() { /* ready */ });
The configuration of $async is 100% JSON and is availale in JSON schemas.
Option | Description | Type |
| The stylesheet URL. |
|
| The script URL. |
|
| A reference to use for dependency or onload events. |
|
| A |
|
| An object of HTML attributes to define on the stylesheet HTML element. |
|
| A base URL for relative URL re-basing. |
|
| A query selector to insert the stylesheet before, or an object. |
|
| A query selector for an DOM element to insert the stylesheet after. |
|
| A query selector for an DOM element to insert the stylesheet after. |
|
| Download timing configuration (see timing module). |
|
| Timing method type ( |
|
| Frame target for method |
|
| Timeout in seconds for methods |
|
| Media Query for method |
|
| Query selector for method |
|
| Offset for method |
|
| Offset from top |
|
| Offset from right |
|
| Offset from bottom |
|
| Offset from left |
|
| Ratio of an elements height and width that needs to be visible for method |
|
| Method name to define on |
|
| Configuration to pass to |
|
|
|
|
| CSS render timing configuration (see timing module). |
|
| See |
|
| Script exec timing configuration (see timing module). |
|
| See |
|
| A string or object with cache configuration (see cache module). |
|
| Cache method, |
|
| Namespace for cache. |
|
| Expire time in seconds. |
|
| Maximum size in bytes to store in cache. |
|
| Methods for CSS source retrieval, |
|
| An object with XHR request configuration. |
|
| An key/value object with HTTP headers to include in the XHR request. |
|
| An string with a CORS proxy URL or a object with CORS proxy configuration. |
|
| A proxy URL. |
|
| The same as |
|
| Background update configuration object. |
|
| Background update interval in seconds. |
|
| Enable/disable HTTP |
|
| The same options as |
|
| A string, object or array of strings and/or objects. |
|
| Dependency match pattern. |
|
| Boolean to enable/disable regular expression based match. |
|
{"href": "sheet.css","dependencies": ["other-sheet.css"],"cache": {"type": "localstorage","max_size": 10000,"fallback": "cache-api","update": {"head": true,"interval": 86400},"source": "cors","cors": {"proxy": "https://cors-anywhere.herokuapp.com/"},"xhr": {"headers": {"x-special-header": "secret-key"}}},"attributes": {"data-app-sheet": "1"},"load_timing": {"type": "inview","selector": "#footer","offset": -250},"render_timing": "requestAnimationFrame"}
Most of the options from the load configuration can be defined in the global configuration to apply to all stylesheets, for example a base
path to resolve relative paths.
The following extra options can be defined via the global options.
Option |
|
|
|
|
|
|
|
$async(["sheet1.css", {"href":"sheet2.css", "ref": "test"}],// global options applied to sheet1.css and sheet2.css// ref from sheet2.css overrides the global ref{"ref": "global-options","load_timing": "domReady"});
// simple async loading$async('sheet.css').then(function() { /* onload */ });
The following complex example displays the use of dependency configuration, download and render timing, URL re-basing (compression), localStorage
cache with Cache-API
fallback for big stylesheets, HTTP HEAD
based background cache update, CORS proxy for caching of external stylesheets, XHR configuration and the ability to define a DOM insert target (after or before a DOM element).
// dependencies, timing and global options$async([ // load 3 stylesheets'sheet.css',{href:'other-sheet.css',dependencies: ['sheet.css'], // wait for sheet.css via dependencies and insert after DOM elementload_timing: {type: 'inview',selector: '#footer', // download stylesheet when footer becomes visible within 250 pixelsoffset: -250}},{href:'mobile-sheet.css',target: {after: 'meta[charset]'},load_timing: {type: 'media', // download stylesheet based on a media query (also works with viewport changes)media: 'screen and (max-width: 600px)'}}],{ // global options applied to all stylesheetsbase: '/long/path/to/css/', // base directory for relative sheet URLscache: {type: "localStorage",max_size: 10000, // cache only <10kbfallback: 'cache-api', // fallback to Cache-API for bigger sheetsupdate: {head: true, // use HTTP HEAD request to check for 304 - Not Modifiedinterval: 86400 // update once per day},source: ['cssText','xhr','cors'], // defaultcors: {proxy: 'https://cors-anywhere.herokuapp.com/', // more proxies on https://gist.github.com/jimmywarting/ac1be6ea0297c16c477e17f8fbe51347},xhr: {headers: {"x-special-header": "secret-key" // request header to include in XHR requests}}},attributes: {"data-app-sheet": "1" // HTML attribute to add to stylesheet element},render_timing: 'requestAnimationFrame' // render via requestAnimationFrame}).then(function() { /* ready */ });
The Async Loader is chainable and provides the option to subscribe to events via the .on
, .once
and off
methods.
// chainable$async.on('load',function(sheet, sheetEl){// sheet.css or other-sheet.css loaded}).on('sheet-ref',function() { }) // sheet with ref-name loaded.on('sheet.css', function() {}); // sheet with href loaded.load({href: 'sheet.css',ref: 'sheet-ref'}).then(function() { }) // sheet.css loaded.load('other-sheet.css');
$async
enables just-in-time
loading of CSS and javascript which can provide a great performance win for many websites. The following example preloads a popup script on domReady
and executes it when the script is needed, saving CPU time for most visitors.
// preload popup script in background$async.js({"ref": "popup","dependencies": "jquery","load_timing": "domReady","exec_timing": {"type": "method","method": "exec_popup_script"}});​// just-in-timejQuery('button.popup').on('click', function() {​// load popup scriptexec_popup_script().then(function() {alert('popup script ready');});});
$async.time
enables to make use of the timing module for any purpose, for example for script startup-time optimization or to execute a script when an element scrolls into view.
$async.time
requires both the API and timing module.
$async.time({"type": "requestIdleCallback","timeout": 3000},function() {// big script},["big-script"]);
With JSON compression it would result in the following:
$async.time({"2":53,"57":3000},function(){}); // 3000ms timeout
A simple requestIdleCallback
with the default timeout:
$async.time("requestIdleCallback", function() {});$async.time(53, function() {}); // compression index