Style Loader
[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]
# style-loader
Inject CSS into the DOM.
## Getting Started
To begin, you'll need to install `style-loader`:
```console
npm install --save-dev style-loader
```
It's recommended to combine `style-loader` with the [`css-loader`](https://github.com/webpack-contrib/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'],
},
],
},
};
```
## Options
| Name | Type | Default | Description |
| :-----------------------------: | :------------------: | :---------: | :------------------------------------------------------- |
| [**`injectType`**](#injecttype) | `{String}` | `styleTag` | Allows to setup how styles will be injected into the DOM |
| [**`attributes`**](#attributes) | `{Object}` | `{}` | Adds custom attributes to tag |
| [**`insert`**](#insert) | `{String\|Function}` | `head` | Inserts tag at the given position into the DOM |
| [**`base`**](#base) | `{Number}` | `true` | Sets module ID base (DLLPlugin) |
| [**`esModule`**](#esmodule) | `{Boolean}` | `false` | Use ES modules syntax |
| [**`modules`**](#modules) | `{Object}` | `undefined` | Configuration CSS Modules |
### `injectType`
Type: `String`
Default: `styleTag`
Allows to setup how styles will be injected into the DOM.
Possible values:
- `styleTag`
- `singletonStyleTag`
- `lazyStyleTag`
- `lazySingletonStyleTag`
- `linkTag`
#### `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 styles from './styles.css';
const divElement = document.createElement('div');
divElement.className = styles['my-class'];
```
All locals (class names) stored in imported object.
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
// The `injectType` option can be avoided because it is default behaviour
{ loader: 'style-loader', options: { injectType: 'styleTag' } },
'css-loader',
],
},
],
},
};
```
The loader inject styles like:
```html
```
#### `singletonStyleTag`
Automatically injects styles into the DOM using one ``.
> ⚠ Source maps do not work.
**component.js**
```js
import './styles.css';
```
**component-with-css-modules.js**
```js
import styles from './styles.css';
const divElement = document.createElement('div');
divElement.className = styles['my-class'];
```
All locals (class names) stored in imported object.
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
{
loader: 'style-loader',
options: { injectType: 'singletonStyleTag' },
},
'css-loader',
],
},
],
},
};
```
The loader inject styles like:
```html
```
#### `lazyStyleTag`
Injects styles into the DOM using multiple `` on demand.
We recommend following `.lazy.css` naming convention for lazy styles and the `.css` for basic `style-loader` usage (similar to other file types, i.e. `.lazy.less` and `.less`).
When you `lazyStyleTag` 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 from './styles.lazy.css';
styles.use();
const divElement = document.createElement('div');
divElement.className = styles.locals['my-class'];
```
All locals (class names) stored in `locals` property of imported object.
**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' } },
'css-loader',
],
},
],
},
};
```
The loader inject styles like:
```html
```
#### `lazySingletonStyleTag`
Injects styles into the DOM using one `` on demand.
We recommend following `.lazy.css` naming convention for lazy styles and the `.css` for basic `style-loader` usage (similar to other file types, i.e. `.lazy.less` and `.less`).
When you `lazySingletonStyleTag` 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 from './styles.lazy.css';
styles.use();
const divElement = document.createElement('div');
divElement.className = styles.locals['my-class'];
```
All locals (class names) stored in `locals` property of imported object.
**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' },
},
'css-loader',
],
},
],
},
};
```
The loader generate this:
```html
```
#### `linkTag`
Injects styles into the DOM using multiple `` .
> ℹ️ The loader will dynamically insert the `` tag at runtime via JavaScript. You should use [MiniCssExtractPlugin](https://webpack.js.org/plugins/mini-css-extract-plugin/) 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
```
### `attributes`
Type: `Object`
Default: `{}`
If defined, the `style-loader` will attach given attributes with their values on `
```
### `insert`
Type: `String|Function`
Default: `head`
By default, the `style-loader` appends `
```
#### `__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
Inserts styles at top of `head` tag.
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
{
loader: 'style-loader',
options: {
insert: 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;
},
},
},
'css-loader',
],
},
],
},
};
```
#### Insert styles before target element
Inserts styles before `#id` element.
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: /\.css$/i,
use: [
{
loader: 'style-loader',
options: {
insert: 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;
},
},
},
'css-loader',
],
},
],
},
};
```
## Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
[CONTRIBUTING](./.github/CONTRIBUTING.md)
## License
[MIT](./LICENSE)
[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
[deps]: https://david-dm.org/webpack-contrib/style-loader.svg
[deps-url]: https://david-dm.org/webpack-contrib/style-loader
[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
[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.now.sh/badge?p=style-loader
[size-url]: https://packagephobia.now.sh/result?p=style-loader