• This repository has been archived on 21/Oct/2022
  • Stars
    star
    6,716
  • Rank 5,888 (Top 0.2 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 10 years ago
  • Updated about 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Load CSS asynchronously

⚠️ This project is archived and the repository is no longer maintained.

loadCSS

A pattern for loading CSS asynchronously [c]2020 @scottjehl, @zachleat Filament Group, Inc. Licensed MIT

Why an ansychronous CSS loader?

Referencing CSS stylesheets with link[rel=stylesheet] or @import causes browsers to delay page rendering while a stylesheet loads. When loading stylesheets that are not critical to the initial rendering of a page, this blocking behavior is undesirable. The pattern below allows us to fetch and apply CSS asynchronously. If necessary, this repo also offers a separate (and optional) JavaScript function for loading stylesheets dynamically.

How to use

As a primary pattern, we recommend loading asynchronous CSS like this from HTML:

<link rel="stylesheet" href="/path/to/my.css" media="print" onload="this.media='all'; this.onload=null;">

This article explains why this approach is best: https://www.filamentgroup.com/lab/load-css-simpler/

That is probably all you need! But if you want to load a CSS file from a JavaScript function, read on...

Dynamic CSS loading with the loadCSS function

The loadCSS.js file exposes a global loadCSS function that you can call to load CSS files programmatically, if needed. This is handy for cases where you need to dynamically load CSS from script.

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

The code above will insert a new CSS stylesheet link after the last stylesheet or script that it finds in the page, and the function will return a reference to that link element, should you want to reference 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.

Function API

The loadCSS 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.
<head>
...
<script id="loadcss">
  // load a CSS file just before the script element containing this code
  loadCSS( "path/to/mystylesheet.css", document.getElementById("loadcss") );
</script>
...
</head>
  • media: You can optionally pass a string to the media argument to set the media="" of the stylesheet - the default value is all.
  • attributes: You can also optionally pass an Object of attribute name/attribute value pairs to set on the stylesheet. This can be used to specify Subresource Integrity attributes:
loadCSS( 
  "https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css",
  null,
  null,
  {
    "crossorigin": "anonymous",
    "integrity": "sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm"
  }
);

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

The loadCSS patterns attempt to load a css file asynchronously in any JavaScript-capable browser. However, some older browsers such as Internet Explorer 8 and older will block rendering while the stylesheet is loading. This merely means that the stylesheet will load as if you referenced it with an ordinary link element.

Changes in version 3.0 (no more preload polyfill)

As of version 3.0, we no longer support or include a polyfill for a rel=preload markup pattern. This is because we have since determined that the markup pattern described at the top of this readme is simpler and better for performance, while the former preload pattern could sometimes conflict with resource priorities in ways that aren't helpful for loading CSS in a non-blocking way.

To update, you can change your preload markup to this HTML pattern and delete the JS from your build.

Since this change breaks the API from prior versions, we made it a major version bump. That way, if you are still needing to use the now-deprecated preload pattern, you can keep your code pointing at prior versions that are still on NPM, such as version 2.1.0 https://github.com/filamentgroup/loadCSS/releases/tag/v2.1.0

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!

More Repositories

1

tablesaw

A group of plugins for responsive tables.
JavaScript
5,481
star
2

grunticon

A mystical CSS icon solution.
HTML
3,304
star
3

criticalCSS

Finds the Above the Fold CSS for your page, and outputs it into a file
JavaScript
1,698
star
4

fixed-sticky

DEPRECATED: A position: sticky polyfill that works with filamentgroup/fixed-fixed for a safer position:fixed fallback.
JavaScript
1,486
star
5

Responsive-Images

NOTE: use Picturefill instead. An Experiment with Mobile-First Images that Scale Responsively & Responsibly
JavaScript
1,382
star
6

SocialCount

Unmaintained (see the README): Simple barebones project to show share counts from various social networks.
JavaScript
1,357
star
7

select-css

Cross-browser styles for consistent select element styling
CSS
1,238
star
8

glyphhanger

Your web font utility belt. It can subset web fonts. It can find unicode-ranges for you automatically. It makes julienne fries.
JavaScript
1,112
star
9

Southstreet

Filament Group's core tools & workflow for delivering rich cross-device web applications
JavaScript
1,087
star
10

Overthrow

A tiny, no-frills, framework-independent, targeted overflow: auto polyfill for use in responsive design.
JavaScript
907
star
11

responsive-carousel

A jQuery-based script for responsive carousels that work with mouse, touch, and keyboard
JavaScript
904
star
12

loadJS

A simple function for asynchronously loading JavaScript files
JavaScript
892
star
13

Ajax-Include-Pattern

An Ajax-Include Pattern for Modular Content
JavaScript
625
star
14

tappy

Retired (see README): Tappy! - a lightweight normalized tap event.
HTML
572
star
15

politespace

Politely add spaces to numeric form values to increase readability (credit card numbers, phone numbers, etc).
JavaScript
535
star
16

grunt-criticalcss

Grunt wrapper for criticalcss
JavaScript
530
star
17

enhance

A JavaScript workflow designed to progressively enhance sites in a qualified manner.
JavaScript
489
star
18

shoestring

A lightweight, simple DOM utility made to run on a tight budget.
JavaScript
440
star
19

imaging-heap

A command line tool to measure the efficiency of your responsive image markup across viewport sizes and device pixel ratios.
JavaScript
401
star
20

snapper

A CSS Snap-Points based carousel (and lightweight polyfill)
JavaScript
361
star
21

jQuery-Visualize

HTML5 canvas charts driven by HTML table elements
JavaScript
353
star
22

a-font-garde

A variety of test cases and tools for safe font-icon usage.
JavaScript
292
star
23

jQuery-UI-Date-Range-Picker

A range picker built on top of jQuery UI's Datepicker Control
JavaScript
272
star
24

X-rayHTML

A little something to help build documentation pages.
JavaScript
258
star
25

AppendAround

A pattern for responsive markup
JavaScript
236
star
26

jqm-pagination

jQuery Mobile Pagination for touch, mouse, and keyboard
JavaScript
213
star
27

jQuery-Equal-Heights

This repository is unmaintained. Please see the included readme for more information.
JavaScript
206
star
28

formcore

A set of forms.
HTML
205
star
29

font-loading

Research on fonts
HTML
193
star
30

quickconcat

a simple dynamic concatenator for html, css, and js files, written in php
PHP
182
star
31

fixed-fixed

CSS position:fixed qualifier.
HTML
178
star
32

RWD-Nav-Patterns

Experimental navigation structure and behavior patterns based on progressive enhancement and responsive web design.
CSS
146
star
33

jQuery-Custom-File-Input

CSS-Friendly File Input
JavaScript
132
star
34

svg-to-png

Turn a folder full of SVGs into PNGs!
JavaScript
125
star
35

layersnap

Build SVG transitions simply and declaratively
JavaScript
110
star
36

woff2-feature-test

A simple feature test for the WOFF2 font format
JavaScript
107
star
37

RWD-Table-Patterns

This repository has been retired. Please see the readme below for more information.
JavaScript
105
star
38

scoped-media-query

An element query workaround. A Sass mixin for scoping CSS styles to apply only within given selector/media query pairs.
SCSS
104
star
39

EnhanceJS

Are you looking for the new "Enhance"? Try here https://github.com/filamentgroup/enhance
JavaScript
104
star
40

html-video-responsive

Explainer repo for a proposal to improve the responsive capabilities of the HTML video element
100
star
41

faux-pas

A script to highlight elements that are mismatched incorrectly to @​font-face blocks, which may result in shoddy faux bold or faux italic rendering.
HTML
99
star
42

jQuery-File-Download

One issue we have not yet seen addressed is the Ajax’s inability to receive a response in any form but text. Since it is now common for web applications to offer options for exporting your data in desktop app formats — such as .doc or .xls — we wrote a jQuery plugin to facilitate requests from the front end that result in a file for download. The plugin does not actually use Ajax, but its syntax follows the conventions of jQuery's native Ajax functions, making it a natural addition to our jQuery toolset.
JavaScript
98
star
43

enlarge

zoom a photo
JavaScript
91
star
44

cookie

Get, set, forget cookies!
JavaScript
91
star
45

elementary

A CSS workflow for mimicking element queries
JavaScript
87
star
46

porthole

Activate stuff when it's in the viewport
JavaScript
86
star
47

jQuery-Menu

Dropdown, iPod Drilldown, and Flyout styles with ARIA Support and ThemeRoller Ready
CSS
83
star
48

collapsible

Toggle your collapsible content
JavaScript
81
star
49

dialog

Just a simple, minimal jQuery dialog with typical interactivity
JavaScript
80
star
50

jQuery-Preload-CSS-Images

A solution that automates the age-old task of preloading images in web applications.
JavaScript
75
star
51

fg-modal

A modal web component
JavaScript
71
star
52

grumpicon

Grunticon Web App.
JavaScript
71
star
53

gulpicon

A gulp task wrapper for grunticon-lib.
Handlebars
67
star
54

jQuery-Custom-Input

Accessible, custom designed checkbox and radio button inputs styled with CSS (and a dash of jQuery)
HTML
63
star
55

checkboxradio

jQuery Plugin for progressively enhanced radio buttons and checkboxes
JavaScript
54
star
56

select

Minimally custom-styled select element
CSS
53
star
57

Revolver

A 360° panoramic photo viewer
JavaScript
50
star
58

resizeasaurus

A little utility to add resizing behavior to test intrinsically sized responsive components.
HTML
49
star
59

jQuery-Pixel-Em-Converter

jQuery Plugin for Retaining Scalable Interfaces with Pixel-to-Em Conversion
JavaScript
48
star
60

jQuery-Mobile-FixedToolbar-Legacy-Polyfill

Brings jQM Fixed Toolbar support to browsers that don't natively support position:fixed (like iOS4)
HTML
43
star
61

grunticon-lib

Stand-alone library for Grunticon
JavaScript
41
star
62

cq

A minimal container query web component
JavaScript
39
star
63

Overthrow-Sidescroller

The Sidescroller extension for Overthrow
JavaScript
37
star
64

jQuery-Mobile-Themed-DatePicker

This is jQuery UI's datepicker plugin with jQuery Mobile's theming and script handling applied.
HTML
36
star
65

auto-complete

A very small auto-complete component.
JavaScript
35
star
66

jQuery-Tree-Control

An accessible HTML tree component
JavaScript
34
star
67

jQuery-Slider

Accessible, custom slider widget based on a standard HTML select
JavaScript
34
star
68

directory-encoder

Takes a directory of images, turns it into some CSS.
JavaScript
33
star
69

anims

Just some CSS utilities for build and loop animations.
CSS
33
star
70

Accessible-jQuery-Tabs

A simple jQuery plugin for accessible tabs widget
HTML
30
star
71

face-off

This repository has been retired. Please see the readme below for more information.
HTML
29
star
72

Heart.js

A lightweight “ticker” plugin.
HTML
28
star
73

tau

Tau is a small and simple 360° gallery
JavaScript
26
star
74

Menu

jQuery Plugin for progressively enhanced menus
JavaScript
26
star
75

jQuery-Collapsible-Content

An accessible collapsible content panel plugin
JavaScript
25
star
76

directory-colorfy

Turn a folder of SVGs into a different color, quickly!
JavaScript
24
star
77

script-media-query

An @media (script) polyfill experiment
JavaScript
21
star
78

fg-carousel

An accessible carousel web component
JavaScript
18
star
79

Details

JavaScript
17
star
80

iconoclash

A workflow for configurable external svg sets.
JavaScript
14
star
81

iframe-caching

HTML
12
star
82

marquee

HTML
11
star
83

creditable

Utilities for working with credit card form input.
JavaScript
11
star
84

postcss-media-query-optimizer

A postcss plugin that will optimize your media queries.
JavaScript
10
star
85

servers-workers

Service Worker examples to be used at the CDN level.
JavaScript
9
star
86

component

just our typical auto enhance-able component skeleton
JavaScript
9
star
87

jqm-mail

An experimental responsive web app layout using jQuery Mobile controls
HTML
8
star
88

fg-collapse

An accessible collapsible web component
JavaScript
8
star
89

getmeta

get a meta tag's value by its name
JavaScript
8
star
90

3D-feature-test

Using progressive enhancement to apply 3D flip animation only to capable browsers
CSS
7
star
91

node-faux-pas

A command line utility to test a URL for faux web font rendering and mismatched web font code.
JavaScript
7
star
92

wc-experiments

web components and such
JavaScript
6
star
93

pym

A lightweight zoom library
JavaScript
4
star
94

validator

Form validation goodies
JavaScript
4
star
95

toss

A JavaScript function that scrolls any overflow container to a set of coordinates using an animated duration.
JavaScript
3
star
96

Trunca-

JavaScript
2
star
97

demo-head

Header for demo pages
CSS
2
star
98

compare-embed

HTML
1
star
99

flex-luthor

A small wrapper library to help with responsive intrinsic-sized Flexbox layouts that wrap based on content and container width and avoiding viewport-based media queries.
Nunjucks
1
star