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}` | `true` | 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