style loader module for webpack
npm install style-loader[![npm][npm]][npm-url]
[![node][node]][node-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![discussion][discussion]][discussion-url]
[![size][size]][size-url]
Inject CSS into the DOM.
To begin, you'll need to install style-loader:
``console`
npm install --save-dev style-loader
or
`console`
yarn add -D style-loader
or
`console`
pnpm add -D style-loader
It's recommended to combine style-loader with the css-loader
Then add the loader to your webpack config. For example:
style.css
`css`
body {
background: green;
}
component.js
`js`
import "./style.css";
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: ["style-loader", "css-loader"],
},
],
},
};
This loader is primarily meant for development. The default settings are not safe for production environments. See the recommended example configuration and the section on nonces for details.
- injectType
- attributes
- insert
- styleTagTransform
- base
- esModule
Type:
`ts`
type injectType =
| "styleTag"
| "singletonStyleTag"
| "autoStyleTag"
| "lazyStyleTag"
| "lazySingletonStyleTag"
| "lazyAutoStyleTag"
| "linkTag";
Default: styleTag
Allows to setup how styles will be injected into the DOM.
Possible values:
#### styleTag
Automatically injects styles into the DOM using multiple . It is default behaviour.
component.js
`js`
import "./styles.css";
Example with Locals (CSS Modules):
component-with-css-modules.js
`js
import * as styles from "./styles.css";
const divElement = document.createElement("div");
divElement.className = styles["my-class"];
`
All local variables (class names) are exported as named exports. To achieve this behaviour you also have to setup modules option for css-loader. For more information consult with css-loader documentation.
webpack.config.js
`jsinjectType
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
// The option can be avoided because it is default behaviour`
{ loader: "style-loader", options: { injectType: "styleTag" } },
{
loader: "css-loader",
// Uncomment it if you want to use CSS modules
// options: { modules: true }
},
],
},
],
},
};
The loader inject styles like:
`html`
#### singletonStyleTag
Automatically injects styles into the DOM using one .
> Warning
>
> Source maps do not work.
component.js
`js`
import "./styles.css";
component-with-css-modules.js
`js
import * as styles from "./styles.css";
const divElement = document.createElement("div");
divElement.className = styles["my-class"];
`
All local variables (class names) are exported as named exports. To achieve this behaviour you also have to setup modules option for css-loader. For more information consult with css-loader documentation.
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
{
loader: "style-loader",
options: { injectType: "singletonStyleTag" },
},
{
loader: "css-loader",
// Uncomment it if you want to use CSS modules
// options: { modules: true }
},
],
},
],
},
};
The loader inject styles like:
`html`
#### autoStyleTag
Works the same as a styleTag, but if the code is executed in IE6-9, turns on the singletonStyleTag mode.
#### lazyStyleTag
Injects styles into the DOM using multiple on demand..lazy.css
We recommend following naming convention for lazy styles and the .css for basic style-loader usage (similar to other file types, i.e. .lazy.less and .less).lazyStyleTag
When you value the style-loader injects the styles lazily making them useable on-demand via style.use() / style.unuse().
> ⚠️ Behavior is undefined when unuse is called more often than use. Don't do that.
component.js
`js
import styles from "./styles.lazy.css";
styles.use();
// For removing styles you can use
// styles.unuse();
`
component-with-css-modules.js
`js
import styles, { "my-class" as myClass } from "./styles.lazy.css";
styles.use();
const divElement = document.createElement("div");
divElement.className = myClass;
`
All local variables (class names) are exported as named exports. To achieve this behaviour you also have to setup modules option for css-loader. For more information consult with css-loader documentation.
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
exclude: /\.lazy\.css$/i,
use: ["style-loader", "css-loader"],
},
{
test: /\.lazy\.css$/i,
use: [
{ loader: "style-loader", options: { injectType: "lazyStyleTag" } },
{
loader: "css-loader",
// Uncomment it if you want to use CSS modules
// options: { modules: true }
},
],
},
],
},
};
The loader inject styles like:
`html`
#### lazySingletonStyleTag
Injects styles into the DOM using one on demand..lazy.css
We recommend following naming convention for lazy styles and the .css for basic style-loader usage (similar to other file types, i.e. .lazy.less and .less).lazySingletonStyleTag
When you value the style-loader injects the styles lazily making them useable on-demand via style.use() / style.unuse().
> ⚠️ Source maps do not work.
> ⚠️ Behavior is undefined when unuse is called more often than use. Don't do that.
component.js
`js
import styles from "./styles.css";
styles.use();
// For removing styles you can use
// styles.unuse();
`
component-with-css-modules.js
`js
import styles, { "my-class" as myClass } from "./styles.lazy.css";
styles.use();
const divElement = document.createElement("div");
divElement.className = myClass;
`
All local variables (class names) are exported as named exports. To achieve this behaviour you also have to setup modules option for css-loader. For more information consult with css-loader documentation.
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
exclude: /\.lazy\.css$/i,
use: ["style-loader", "css-loader"],
},
{
test: /\.lazy\.css$/i,
use: [
{
loader: "style-loader",
options: { injectType: "lazySingletonStyleTag" },
},
{
loader: "css-loader",
// Uncomment it if you want to use CSS modules
// options: { modules: true }
},
],
},
],
},
};
The loader generate this:
`html`
#### lazyAutoStyleTag
Works the same as a lazyStyleTag, but if the code is executed in IE6-9, turns on the lazySingletonStyleTag mode.
#### linkTag
Injects styles into the DOM using multiple .
> ℹ️ The loader will dynamically insert the tag at runtime via JavaScript. You should use MiniCssExtractPlugin if you want to include a static .
`js`
import "./styles.css";
import "./other-styles.css";
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.link\.css$/i,
use: [
{ loader: "style-loader", options: { injectType: "linkTag" } },
{ loader: "file-loader" },
],
},
],
},
};
The loader generate this:
`html`
Type:
`ts`
type attributes = HTMLAttributes;
Default: {}
If defined, the style-loader will attach given attributes with their values on
`
Type:
`ts`
type insert = string;
Default: head
By default, the style-loader appends and works faster.
> Warning
>
> Do not use together style-loader and mini-css-extract-plugin.
webpack.config.js
`js
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const devMode = process.env.NODE_ENV !== "production";
module.exports = {
module: {
rules: [
{
test: /\.(sa|sc|c)ss$/,
use: [
devMode ? "style-loader" : MiniCssExtractPlugin.loader,
"css-loader",
"postcss-loader",
"sass-loader",
],
},
],
},
plugins: [].concat(devMode ? [] : [new MiniCssExtractPlugin()]),
};
`
> Warning
>
> It is not allowed to use JavaScript reserved words in css class names.
> Warning
>
> Options esModule and modules.namedExport in css-loader should be enabled (by default for css-loader@7 it is true).
styles.css
`css`
.fooBaz {
color: red;
}
.bar {
color: blue;
}
.my-class {
color: green;
}
index.js
`js
import { fooBaz, bar, "my-class" as myClass } from "./styles.css";
console.log(fooBaz, bar, myClass);
`
Or:
index.js
`js
import * as styles from "./styles.css";
console.log(styles.fooBaz, styles.bar, styles["my-class"]);
`
You can enable a ES module named export using:
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: "style-loader",
},
{
loader: "css-loader",
options: {
modules: {
namedExport: true,
},
},
},
],
},
],
},
};
The loader automatically inject source maps when previous loader emit them.
Therefore, to generate source maps, set the sourceMap option to true for the previous loader.
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
"style-loader",
{ loader: "css-loader", options: { sourceMap: true } },
],
},
],
},
};
If you are using a Content Security Policy (CSP), the injected code will usually be blocked. A workaround is to use a nonce. Note, however, that using a nonce significantly reduces the protection provided by the CSP. You can read more about the security impact in the specification. The better solution is not to use this loader in production.
There are two ways to work with nonce:
- using the attributes option__webpack_nonce__
- using the variable
> Warning
>
> the attributes option takes precedence over the __webpack_nonce__ variable
#### attributes
component.js
`js`
import "./style.css";
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
{
loader: "style-loader",
options: {
attributes: {
nonce: "12345678",
},
},
},
"css-loader",
],
},
],
},
};
The loader generate:
`html`
#### __webpack_nonce__
create-nonce.js
`js`
__webpack_nonce__ = "12345678";
component.js
`js`
import "./create-nonce.js";
import "./style.css";
Alternative example for require:
component.js
`js
__webpack_nonce__ = "12345678";
require("./style.css");
`
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: ["style-loader", "css-loader"],
},
],
},
};
The loader generate:
`html`
#### Insert styles at top
Insert styles at top of head tag.
insert-function.js
`js
function insertAtTop(element) {
var parent = document.querySelector("head");
var lastInsertedElement = window._lastElementInsertedByStyleLoader;
if (!lastInsertedElement) {
parent.insertBefore(element, parent.firstChild);
} else if (lastInsertedElement.nextSibling) {
parent.insertBefore(element, lastInsertedElement.nextSibling);
} else {
parent.appendChild(element);
}
window._lastElementInsertedByStyleLoader = element;
}
module.exports = insertAtTop;
`
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
{
loader: "style-loader",
options: {
insert: require.resolve("./insert-function.js"),
},
},
"css-loader",
],
},
],
},
};
#### Insert styles before target element
Inserts styles before #id element.
insert-function.js
`js
function insertBeforeAt(element) {
const parent = document.querySelector("head");
const target = document.querySelector("#id");
const lastInsertedElement = window._lastElementInsertedByStyleLoader;
if (!lastInsertedElement) {
parent.insertBefore(element, target);
} else if (lastInsertedElement.nextSibling) {
parent.insertBefore(element, lastInsertedElement.nextSibling);
} else {
parent.appendChild(element);
}
window._lastElementInsertedByStyleLoader = element;
}
module.exports = insertBeforeAt;
`
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
{
loader: "style-loader",
options: {
insert: require.resolve("./insert-function.js"),
},
},
"css-loader",
],
},
],
},
};
#### Custom Elements (Shadow DOM)
You can define custom target for your styles for the lazyStyleTag type.
insert-function.js
`js
function insertIntoTarget(element, options) {
var parent = options.target || document.head;
parent.appendChild(element);
}
module.exports = insertIntoTarget;
`
webpack.config.js
`jslet
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
{
loader: "style-loader",
options: {
injectType: "lazyStyleTag",
// Do not forget that this code will be used in the browser and
// not all browsers support latest ECMA features like , const, arrow function expression and etc,`
// we recommend use only ECMA 5 features,
// but it is depends what browsers you want to support
insert: require.resolve("./insert-function.js"),
},
},
"css-loader",
],
},
],
},
};
Insert styles to the provided element or to the head tag if target isn't provided.
custom-square.css
`css`
div {
width: 50px;
height: 50px;
background-color: red;
}
custom-square.js
`js
import customSquareStyles from "./custom-square.css";
class CustomSquare extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: "open" });
const divElement = document.createElement("div");
divElement.textContent = "Text content.";
this.shadowRoot.appendChild(divElement);
customSquareStyles.use({ target: this.shadowRoot });
// You can override injected styles
const bgPurple = new CSSStyleSheet();
const width = this.getAttribute("w");
const height = this.getAttribute("h");
bgPurple.replace(div { width: ${width}px; height: ${height}px; });
this.shadowRoot.adoptedStyleSheets = [bgPurple];
// divElement will have 100px width, 100px height and red background color
}
}
customElements.define("custom-square", CustomSquare);
export default CustomSquare;
``
Please take a moment to read our contributing guidelines if you haven't yet done so.
[npm]: https://img.shields.io/npm/v/style-loader.svg
[npm-url]: https://npmjs.com/package/style-loader
[node]: https://img.shields.io/node/v/style-loader.svg
[node-url]: https://nodejs.org
[tests]: https://github.com/webpack-contrib/style-loader/workflows/style-loader/badge.svg
[tests-url]: https://github.com/webpack-contrib/style-loader/actions
[cover]: https://codecov.io/gh/webpack-contrib/style-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/style-loader
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
[discussion-url]: https://github.com/webpack/webpack/discussions
[size]: https://packagephobia.now.sh/badge?p=style-loader
[size-url]: https://packagephobia.now.sh/result?p=style-loader