Usage
$async can be used as a javascript function or through a HTML attribute on a script element.
$async accepts 8 arguments:
  1. 1.
    CSS loader config
  2. 2.
    CSS loader global options
  3. 3.
    CSS capture config
  4. 4.
    CSS capture global options
  5. 5.
    Javascript loader config
  6. 6.
    Javascript loader global options
  7. 7.
    Javascript capture config
  8. 8.
    Javascript capture global options
1
$async(
2
[/*stylesheets*/], // string, object or an array of strings or objects
3
{/*options*/}, // object
4
[/*capture*/], // string, object or an array of strings or objects
5
{/*capture options*/}, // object
6
7
[/*scripts*/], // string, object or an array of strings or objects
8
{/*options*/}, // object
9
[/*capture*/], // string, object or an array of strings or objects
10
{/*capture options*/} // object
11
).then(function() { /* ready */ });
Copied!
Usage through a HTML attribute.
1
<script async src="js/async-iife.js" data-c='[
2
[/*stylesheets*/], // string, object or an array of strings or objects
3
{/*options*/}, // object
4
[/*capture*/], // string, object or an array of strings or objects
5
{/*capture options*/}, // object
6
7
[/*scripts*/], // string, object or an array of strings or objects
8
{/*options*/}, // object
9
[/*capture*/], // string, object or an array of strings or objects
10
{/*capture options*/} // object
11
]'></script>
Copied!
$async is chainable and provides an API.
1
// alternative load method for chaining when using the API module
2
$async
3
.load(/*...*/) // CSS loader that accepts 8 arguments
4
.js(/**/) // javascript loader only
5
.then(function() { /* ready */ });
Copied!

Configuration

The configuration of $async is 100% JSON and is availale in JSON schemas.
Option
Description
Type
href
The stylesheet URL.
String
src
The script URL.
String
ref
A reference to use for dependency or onload events.
String
media
A media attribute to define on the stylesheet HTML element.
String
attributes
An object of HTML attributes to define on the stylesheet HTML element.
Object
base
A base URL for relative URL re-basing.
String
target
A query selector to insert the stylesheet before, or an object.
false, String or Object
target.after
A query selector for an DOM element to insert the stylesheet after.
String
target.before
A query selector for an DOM element to insert the stylesheet after.
String
load_timing
Download timing configuration (see timing module).
String or Object
load_timing.type
Timing method type (domReady, setTimeout, requestAnimationFrame, requestIdleCallback, inview, lazy, media, method)
String
load_timing.frame
Frame target for method requestAnimationFrame
Number
load_timing.timeout
Timeout in seconds for methods requestIdleCallback and requestAnimationFrame
Number
load_timing.media
Media Query for method media (responsive)
String
load_timing.selector
Query selector for method inview
String
load_timing.offset
Offset for method inview, see in-view
Number or Object
load_timing.offset.top
Offset from top
Number
load_timing.offset.right
Offset from right
Number
load_timing.offset.bottom
Offset from bottom
Number
load_timing.offset.left
Offset from left
Number
load_timing.threshold
Ratio of an elements height and width that needs to be visible for method inview
Number
load_timing.method
Method name to define on window to trigger the callback.
String
load_timing.config
Configuration to pass to $lazy.
String, Object or Array
load_timing.ref
$lazy dependency to wait for.
String
render_timing
CSS render timing configuration (see timing module).
String or Object
render_timing.*
See load_timing.*
Object
exec_timing
Script exec timing configuration (see timing module).
String or Object
exec_timing.*
See load_timing.*
Object
cache
A string or object with cache configuration (see cache module).
String or Object
cache.type
Cache method, localstorage or cache-api.
String
cache.namespace
Namespace for cache.
String
cache.expire
Expire time in seconds.
Number
cache.max_size
Maximum size in bytes to store in cache.
Number
cache.source
Methods for CSS source retrieval, cssText, xhr or cors
String or Array
cache.xhr
An object with XHR request configuration.
Object
cache.xhr.headers
An key/value object with HTTP headers to include in the XHR request.
Object
cache.cors
An string with a CORS proxy URL or a object with CORS proxy configuration.
String or Object
cache.cors.proxy
A proxy URL.
String
cache.cors.xhr
The same as cache.xhr (override for proxy).
Object
cache.update
Background update configuration object.
Object
cache.update.interval
Background update interval in seconds.
Number
cache.update.head
Enable/disable HTTP HEAD 304 - Not Modified check based update.
Boolean
cache.fallback
The same options as cache to use as fallback.
String or Object
dependencies
A string, object or array of strings and/or objects.
String or Object
dependencies.match
Dependency match pattern.
String
dependencies.regex
Boolean to enable/disable regular expression based match.
Boolean

Example JSON

1
{
2
"href": "sheet.css",
3
"dependencies": [
4
"other-sheet.css"
5
],
6
"cache": {
7
"type": "localstorage",
8
"max_size": 10000,
9
"fallback": "cache-api",
10
"update": {
11
"head": true,
12
"interval": 86400
13
},
14
"source": "cors",
15
"cors": {
16
"proxy": "https://cors-anywhere.herokuapp.com/"
17
},
18
"xhr": {
19
"headers": {
20
"x-special-header": "secret-key"
21
}
22
}
23
},
24
"attributes": {
25
"data-app-sheet": "1"
26
},
27
"load_timing": {
28
"type": "inview",
29
"selector": "#footer",
30
"offset": -250
31
},
32
"render_timing": "requestAnimationFrame"
33
}
Copied!

Global options

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
media
attributes
base
target
load_timing
render_timing
cache
1
$async(
2
["sheet1.css", {"href":"sheet2.css", "ref": "test"}],
3
// global options applied to sheet1.css and sheet2.css
4
// ref from sheet2.css overrides the global ref
5
{
6
"ref": "global-options",
7
"load_timing": "domReady"
8
});
Copied!

Examples

Simple async loading

1
// simple async loading
2
$async('sheet.css').then(function() { /* onload */ });
Copied!

Timed and dependency based loading

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).
1
// dependencies, timing and global options
2
$async(
3
[ // load 3 stylesheets
4
'sheet.css',
5
{
6
href:'other-sheet.css',
7
dependencies: ['sheet.css'], // wait for sheet.css via dependencies and insert after DOM element
8
load_timing: {
9
type: 'inview',
10
selector: '#footer', // download stylesheet when footer becomes visible within 250 pixels
11
offset: -250
12
}
13
},
14
{
15
href:'mobile-sheet.css',
16
target: {
17
after: 'meta[charset]'
18
},
19
load_timing: {
20
type: 'media', // download stylesheet based on a media query (also works with viewport changes)
21
media: 'screen and (max-width: 600px)'
22
}
23
}
24
],
25
{ // global options applied to all stylesheets
26
base: '/long/path/to/css/', // base directory for relative sheet URLs
27
cache: {
28
type: "localStorage",
29
max_size: 10000, // cache only <10kb
30
fallback: 'cache-api', // fallback to Cache-API for bigger sheets
31
update: {
32
head: true, // use HTTP HEAD request to check for 304 - Not Modified
33
interval: 86400 // update once per day
34
},
35
source: ['cssText','xhr','cors'], // default
36
cors: {
37
proxy: 'https://cors-anywhere.herokuapp.com/', // more proxies on https://gist.github.com/jimmywarting/ac1be6ea0297c16c477e17f8fbe51347
38
},
39
xhr: {
40
headers: {
41
"x-special-header": "secret-key" // request header to include in XHR requests
42
}
43
}
44
},
45
attributes: {
46
"data-app-sheet": "1" // HTML attribute to add to stylesheet element
47
},
48
render_timing: 'requestAnimationFrame' // render via requestAnimationFrame
49
}
50
).then(function() { /* ready */ });
Copied!

Chainable and events

The Async Loader is chainable and provides the option to subscribe to events via the .on, .once and off methods.
1
// chainable
2
$async
3
.on('load',function(sheet, sheetEl){
4
// sheet.css or other-sheet.css loaded
5
})
6
.on('sheet-ref',function() { }) // sheet with ref-name loaded
7
.on('sheet.css', function() {}); // sheet with href loaded
8
.load({
9
href: 'sheet.css',
10
ref: 'sheet-ref'
11
})
12
.then(function() { }) // sheet.css loaded
13
.load('other-sheet.css');
Copied!

Example just-in-time loading

$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.
1
// preload popup script in background
2
$async.js({
3
"ref": "popup",
4
"dependencies": "jquery",
5
"load_timing": "domReady",
6
"exec_timing": {
7
"type": "method",
8
"method": "exec_popup_script"
9
}
10
});
11
12
// just-in-time
13
jQuery('button.popup').on('click', function() {
14
15
// load popup script
16
exec_popup_script().then(function() {
17
alert('popup script ready');
18
});
19
});
Copied!

Custom timing

$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.
1
$async.time(
2
{
3
"type": "requestIdleCallback",
4
"timeout": 3000
5
},
6
function() {
7
// big script
8
},
9
["big-script"]
10
);
Copied!
With JSON compression it would result in the following:
1
$async.time({"2":53,"57":3000},function(){}); // 3000ms timeout
Copied!
A simple requestIdleCallback with the default timeout:
1
$async.time("requestIdleCallback", function() {});
2
$async.time(53, function() {}); // compression index
Copied!
Last modified 1yr ago