Nascent Political Miscreant


    1.0.5 • Public • Published

    lazyload-css 😴 · Build Status npm version

    Promise based method for adding a style sheet to the page if it has not already been added


    yarn add lazyload-css
    bower install lazyload-css --save

    Weigh In

    Imported Weight

    When used with require() you'll notice very little weight is added to your bundle.

    const lazyLoadCSS = require('lazyLoadCSS');

    VanillaJS Weight

    Script Disk Size GZIP
    lazyload-css.1.0.0.js 4.36kB 1.39kB
    lazyload-css.1.0.0.min.js 1.47kB 718b

    The UMD module wrapper weighs more than the lazyLoadCSS() method itself.
    If you want to go rogue, you can load directly from source.


    lazyLoadCSS accepts two parameters. The path to the script to load and an optional id or configuration Object.

    lazyLoadCSS('css/main.css', 'main').then(() => {
      // main.css is loaded now with an id of main

    The id parameter is optional. It is used to ensure that subsequent requests to load a script with that same id immediately resolve. If you omit the id parameter, the DOM will first be queried for a <link> with the same href attribute, before making a new request by appending a new <link> tag.

    lazyLoadCSS uses this id to ensure scripts with the same id are only loaded once. This allows web components to request dependencies with lazyLoadCSS and rest assured the sheets will only be loaded once regardless of how many times they are requested.

    lazyLoadCSS is packaged as a UMD module so it can be included in several ways.

    The UMD pattern typically attempts to offer compatibility with the most popular script loaders of the day (e.g RequireJS amongst others). In many cases it uses AMD as a base, with special-casing added to handle CommonJS compatibility.
     — umd

    With require()

    const lazyLoadCSS = require(`lazyLoadCSS`);
    lazyLoadCSS('main.css', 'main').then(() => {
      /// main.css loaded

    With VanillaJS

    lazyLoadCSS('main.css', 'main').then(() => {
      /// main.css loaded

    Multiple stylesheets can be asynchronously loaded by passing an Array of lazyLoadCSS promises to Promise.all().

        lazyLoadCSS("assets/css/base.css", "base"),
        lazyLoadCSS("assets/css/layout.css", "layout")
      ]).then(() => {
        // stylesheets are loaded now


    lazyLoadCSS accepts two parameters. The path to the script to load and an optional id or configuration Object.

    Option Default Description
    id undefined Used to ensure the same stylesheet isn't added twice
    media 'all' media attribute of the <link> to be added
    rel 'stylesheet' rel attribute of the <link> to be added
    type text/css type attribute of the <link> to be added
    force false If true forces an asset to be loaded even if another with the same id or href are found

    In the below example, unless lazyLoadCSS already loaded a <link> with the same id or href, <link type="text/css" rel="stylesheet" media="all" href="main.css" /> will be appended to document.head.

    lazyLoadCSS('main.css', {
      id: 'main',
      media: 'screen'
    }).then((link) => {
      // link is either the newly added stylesheet or the one that was already there

    In the next example, a stylesheet will forcefully be added regardless of if one with the same href or id already exists.

    lazyLoadCSS('print.css', {
      id: 'print',
      media: 'print',
      force: true
    }).then((link) => {
      // link is the newly added stylesheet

    See Also

    ✅ Getting Started

    We're going to use yarn so make sure that is installed.

    npm install yarn -g

    Now clone the repo and run the tests.

    git clone -b master git://
    cd lazyload-css
    yarn test


    npm i lazyload-css

    DownloadsWeekly Downloads






    Unpacked Size

    149 kB

    Total Files


    Last publish


    • jpdevries