style-loader

What is style-loader?

The style-loader npm package is used to inject CSS into the DOM using multiple strategies. It is often used in combination with css-loader in webpack configurations to handle styles within JavaScript modules.

What are style-loader's main functionalities?

Inject styles into the DOM

This code sample demonstrates how to use style-loader in combination with css-loader to import a CSS file and inject the styles into the DOM.

import style from 'style-loader!css-loader!./style.css';

Useable styles

This code sample shows how to use the useable feature of style-loader to manually control when styles are injected into and removed from the DOM.

import style from 'style-loader/useable!css-loader!./style.css';
style.use(); // Injects styles
tyle.unuse(); // Removes styles

Lazy loading styles

This code sample illustrates how to lazy load styles with style-loader, which can be useful for code splitting scenarios.

import loadStyle from 'style-loader!css-loader!./style.css';
loadStyle().then(style => {
  // Use style here
});

Other packages similar to style-loader

css-loader

css-loader interprets @import and url() like import/require() and will resolve them. It is often used alongside style-loader in webpack configurations.

mini-css-extract-plugin

This webpack plugin extracts CSS into separate files. It creates a CSS file per JS file which contains CSS. It is useful for caching and parallel loading but does not inject styles into the DOM like style-loader.

sass-loader

sass-loader compiles Sass/SCSS files to CSS. It is used in combination with css-loader and style-loader in webpack configurations to handle styles written in Sass/SCSS.

README

style loader for webpack

Usage

Documentation: Using loaders

Simple API

require("style!raw!./file.css");
// => add rules in file.css to document

It's recommended to combine it with the css-loader: require("style!css!./file.css").

It also possible to add a URL instead of a css string:

require("style/url!file!./file.css");
// => add a <link rel="stylesheet"> to file.css to document

Placeholders

(experimental)

When using placeholders (see css-loader) the module exports the placeholders object:

var styles = require("style!css!./file.css");
style.placeholder1 === "z849f98ca812bc0d099a43e0f90184"

Reference-counted API

var style = require("style/useable!css!./file.css");
style.use(); // = style.ref();
style.unuse(); // = style.unref();

Styles are not added on require, but instead on call to use/ref. Styles are removed from page if unuse/unref is called exactly as often as use/ref.

Note: Behavior is undefined when unuse/unref is called more often than use/ref. Don't do that.

Options

singleton

If defined, the style-loader will re-use a single <style> element, instead of adding/removing individual elements for each required module. Note: this option is on by default in IE9, which has strict limitations on the # of style tags allowed on a page. You can enable or disable it with the singleton query parameter (?singleton or ?-singleton).

Recommended configuration

By convention the reference-counted API should be bound to .useable.css and the simple API to .css (similar to other file types, i. e. .useable.less and .less).

So the recommended configuration for webpack is:

{
  module: {
    loaders: [
      { test: /\.css$/, exclude: /\.useable\.css$/, loader: "style!css" },
      { test: /\.useable\.css$/, loader: "style/useable!css" }
    ]
  }
}

Install

npm install style-loader

License

MIT (http://www.opensource.org/licenses/mit-license.php)