fg-loadcss
Advanced tools
fg-loadcss - npm Package Compare versions
Comparing version 1.0.0-0 to 1.0.0
| { | ||
| "name": "fg-loadcss", | ||
| "version": "1.0.0-0", | ||
| "version": "1.0.0", | ||
| "description": "A function for loading CSS asynchronously", | ||
@@ -20,3 +20,3 @@ "main": "src/loadCSS.js", | ||
| "grunt-contrib-jshint": "~0.12.0", | ||
| "grunt-contrib-qunit": "~0.7.0" | ||
| "grunt-contrib-qunit": "~1.0.1" | ||
| }, | ||
@@ -23,0 +23,0 @@ "scripts": { |
| # loadCSS | ||
| A function for loading CSS asynchronously | ||
| [c]2015 @scottjehl, Filament Group, Inc. | ||
| [c]2016 @scottjehl, [Filament Group, Inc.](https://www.filamentgroup.com/) | ||
| Licensed MIT | ||
| ## Usage | ||
| ## Why loadCSS? | ||
| Place the [`loadCSS` function](https://github.com/filamentgroup/loadCSS/blob/master/src/loadCSS.js) inline in the `head` of your page (it can also be included in an external JavaScript file if preferable). | ||
| 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. | ||
| Then call it by passing it a stylesheet URL: | ||
| ## Basic Usage | ||
| ``` html | ||
| <head> | ||
| ... | ||
| <script> | ||
| // include loadCSS here... | ||
| function loadCSS( href, before, media ){ ... } | ||
| // load a file | ||
| loadCSS( "path/to/mystylesheet.css" ); | ||
| </script> | ||
| <noscript><link href="path/to/mystylesheet.css" rel="stylesheet"></noscript> | ||
| ... | ||
| </head> | ||
| With the [`loadCSS` function](https://github.com/filamentgroup/loadCSS/blob/master/src/loadCSS.js) referenced in your page, simply call the `loadCSS` function and pass it a stylesheet URL: | ||
| ```css | ||
| loadCSS( "path/to/mystylesheet.css" ); | ||
| ``` | ||
| By default, loadCSS will inject the new CSS stylesheet *after* the last stylesheet or script in the page. This should retain your CSS cascade as you'd expect. | ||
| 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. | ||
| #### Optional Arguments | ||
| ## 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](https://www.w3.org/TR/2015/WD-preload-20150721/)). 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: | ||
| ```html | ||
| <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](https://github.com/filamentgroup/loadCSS/blob/master/src/onloadCSS.js), as well as the [loadCSS rel=preload polyfill script](https://github.com/filamentgroup/loadCSS/blob/master/src/cssrelpreload.js) 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`. | ||
@@ -35,8 +52,5 @@ ``` html | ||
| <script id="loadcss"> | ||
| // include loadCSS here... | ||
| function loadCSS( href, before, media ){ ... } | ||
| // load a file | ||
| // load a CSS file just before the script element containing this code | ||
| loadCSS( "path/to/mystylesheet.css", document.getElementById("loadcss") ); | ||
| </script> | ||
| <noscript><link href="path/to/mystylesheet.css" rel="stylesheet"></noscript> | ||
| ... | ||
@@ -50,10 +64,8 @@ </head> | ||
| Onload listener support with `link` elements is spotty, so if you need to add an onload callback, include [`onloadCSS` function](https://github.com/filamentgroup/loadCSS/blob/master/src/onloadCSS.js) on your page and use the `onloadCSS` function: | ||
| Onload event support for `link` elements is spotty in some browsers, so if you need to add an onload callback, include [`onloadCSS` function](https://github.com/filamentgroup/loadCSS/blob/master/src/onloadCSS.js) on your page and use the `onloadCSS` function: | ||
| ``` javascript | ||
| function onloadCSS( ss, callback ){ ... } | ||
| var stylesheet = loadCSS( "path/to/mystylesheet.css" ); | ||
| onloadCSS( stylesheet, function() { | ||
| console.log( "Stylesheet has asynchronously loaded." ); | ||
| console.log( "Stylesheet has loaded." ); | ||
| }); | ||
@@ -64,3 +76,3 @@ ``` | ||
| LoadCSS attempts to load a css file asynchronously, while maintaining the CSS cascade, 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. | ||
| 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. | ||
@@ -160,5 +172,4 @@ <table> | ||
| We typically use `loadCSS` to load CSS files that are non-critical to the initial rendering of a site. See the [EnhanceJS project Readme](https://github.com/filamentgroup/enhance#enhancejs) for examples of how we typically use it to improve page loading performance. | ||
| We typically use `loadCSS` to load CSS files that are non-critical to the initial rendering of a page. See the [EnhanceJS project Readme](https://github.com/filamentgroup/enhance#enhancejs) 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). | ||
| The reason this script is sometimes necessary is because there is no cross-browser means in HTML (currently at least) to load and apply a CSS file asynchronously. CSS references that use either `link` or `import` will cause browsers to block page rendering by default while their related stylesheet loads. | ||
@@ -165,0 +176,0 @@ #### Contributions and bug fixes |
@@ -13,3 +13,2 @@ /*! loadCSS: load a CSS file asynchronously. [c]2016 @scottjehl, Filament Group, Inc. Licensed MIT */ | ||
| var ss = doc.createElement( "link" ); | ||
| var newMedia = media || "all"; | ||
| var ref; | ||
@@ -59,14 +58,15 @@ if( before ){ | ||
| function loadCB(){ | ||
| if( ss.addEventListener ){ | ||
| ss.removeEventListener( "load", loadCB ); | ||
| } | ||
| ss.media = media || "all"; | ||
| } | ||
| // once loaded, set link's media back to `all` so that the stylesheet applies once it loads | ||
| if( ss.addEventListener ){ | ||
| ss.addEventListener( "load", function(){ | ||
| this.media = newMedia; | ||
| }); | ||
| ss.addEventListener( "load", loadCB); | ||
| } | ||
| ss.onloadcssdefined = onloadcssdefined; | ||
| onloadcssdefined(function() { | ||
| if( ss.media !== newMedia ){ | ||
| ss.media = newMedia; | ||
| } | ||
| }); | ||
| onloadcssdefined( loadCB ); | ||
| return ss; | ||
@@ -73,0 +73,0 @@ }; |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
No v1
QualityPackage is not semver >=1. This means it is not stable and does not support ^ ranges.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by4.89%
98708
- Number of package files
- increased by4%
26
- Number of low quality alerts
- decreased by-100%
0
- Number of lines in readme file
- increased by6.71%
175
Worsened metrics
- Lines of code
- decreased by-0.04%
2350
No dependency changes