newer-universal-style-loader/README.md

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![chat][chat]][chat-url]

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
  <h1>Style Loader</h1>
</div>

Adds CSS to the DOM by injecting a `<style>` tag

<h2 align="center">Install</h2>

```
npm install style-loader --save-dev
```

<h2 align="center">Usage</h2>

[Documentation: Using loaders](http://webpack.github.io/docs/using-loaders.html)

### Simple API

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

It's recommended to combine it with the [`css-loader`](https://github.com/webpack/css-loader): `require("style-loader!css-loader!./file.css")`.

It's also possible to add a URL instead of a CSS string:

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

### Local scope CSS

(experimental)

When using [local scope CSS](https://github.com/webpack/css-loader#css-scope) the module exports the generated identifiers:

``` javascript
var style = require("style-loader!css-loader!./file.css");
style.placeholder1 === "z849f98ca812bc0d099a43e0f90184"
```

### Reference-counted API

``` javascript
var style = require("style-loader/useable!css-loader!./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

#### `insertAt`

By default, the style-loader appends `<style>` elements to the end of the `<head>` tag of the page. This will cause CSS created by the loader to take priority over CSS already present in the document head. To insert style elements at the beginning of the head, set this query parameter to 'top', e.g. `require('../style.css?insertAt=top')`.

#### `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 number of style tags allowed on a page. You can enable or disable it with the singleton query parameter (`?singleton` or `?-singleton`).

#### `attrs`

If defined, style-loader will attach given attributes with their values on `<style>` / `<link>` element.
Usage:
```javascript
require('style-loader?{attrs:{id: "style-tag-id"}}!style.scss');

// will create style tag <style id="style-tag-id">
```

### 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:

``` javascript
{
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
        ],
      },
      {
        test: /\.useable\.css$/,
        use: [
          {
            loader: "style-loader/useable"
          },
          { loader: "css-loader" },
        ],
      },
    ],
  },
}
```

**Note** about source maps support and assets referenced with `url`: when style loader is used with ?sourceMap option, the CSS modules will be generated as `Blob`s, so relative paths don't work (they would be relative to `chrome:blob` or `chrome:devtools`). In order for assets to maintain correct paths setting `output.publicPath` property of webpack configuration must be set, so that absolute paths are generated.

<h2 align="center">Contributing</h2>

Don't hesitate to create a pull request. Every contribution is appreciated. In development you can start the tests by calling `npm test`.

<h2 align="center">Maintainers</h2>

<table>
  <tbody>
    <tr>
      <td align="center">
        <img width="150 height="150"
        src="https://avatars.githubusercontent.com/sokra?v=3">
        <br />
        <a href="https://github.com/">Tobias Koppers</a>
      </td>
      <td align="center">
        <img width="150 height="150"
        src="https://avatars.githubusercontent.com/SpaceK33z?v=3">
        <br />
        <a href="https://github.com/">Kees Kluskens</a>
      </td>
    <tr>
  <tbody>
</table>


<h2 align="center">LICENSE</h2>

MIT

[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/style-loader.svg
[deps-url]: https://david-dm.org/webpack/file-loader

[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack
chore(readme): Update to webpack standard format 2017-01-11 18:49:17 +03:00			`[![npm][npm]][npm-url]`
			`[![node][node]][node-url]`
			`[![deps][deps]][deps-url]`
			`[![chat][chat]][chat-url]`

			`<div align="center">`
			`<a href="https://github.com/webpack/webpack">`
			`<img width="200" height="200"`
			`src="https://webpack.js.org/assets/icon-square-big.svg">`
			`</a>`
			`<h1>Style Loader</h1>`
			`</div>`
Initial commit 2012-04-07 05:06:57 +04:00
add a one-line description of what the style-loader actually does 2016-05-02 12:05:37 +03:00			Adds CSS to the DOM by injecting a `<style>` tag

chore(readme): Update to webpack standard format 2017-01-11 18:49:17 +03:00			`<h2 align="center">Install</h2>`
Update README.md * Change position of 'Install' section. * Add --save-dev to install script 2016-11-17 18:30:53 +03:00
			```
			`npm install style-loader --save-dev`
			```

chore(readme): Update to webpack standard format 2017-01-11 18:49:17 +03:00			`<h2 align="center">Usage</h2>`
Initial commit 2012-04-07 05:06:57 +04:00
Update README.md 2014-03-11 22:40:59 +04:00			`[Documentation: Using loaders](http://webpack.github.io/docs/using-loaders.html)`

added ref-counted api fixes #4 2014-01-27 14:41:56 +04:00			`### Simple API`

Initial commit 2012-04-07 05:06:57 +04:00			``` javascript
Add -loader suffix to reflect new loader syntax webpack 2 requirement 2016-11-16 21:45:57 +03:00			`require("style-loader!raw-loader!./file.css");`
Initial commit 2012-04-07 05:06:57 +04:00			`// => add rules in file.css to document`
			```

Add -loader suffix to reflect new loader syntax webpack 2 requirement 2016-11-16 21:45:57 +03:00			It's recommended to combine it with the [`css-loader`](https://github.com/webpack/css-loader): `require("style-loader!css-loader!./file.css")`.
fixed docs 2012-07-17 04:11:39 +04:00
Update README.md 2015-12-06 08:01:04 +03:00			`It's also possible to add a URL instead of a CSS string:`
added style/url to readme 2013-03-26 14:51:42 +04:00
			``` javascript
Add -loader suffix to reflect new loader syntax webpack 2 requirement 2016-11-16 21:45:57 +03:00			`require("style-loader/url!file-loader!./file.css");`
Update README.md 2014-10-23 16:31:22 +04:00			`// => add a <link rel="stylesheet"> to file.css to document`
added style/url to readme 2013-03-26 14:51:42 +04:00			```

Replace "placeholders" with "local scope CSS" 2015-12-06 08:08:01 +03:00			`### Local scope CSS`
added placeholders section to readme 2015-04-22 00:40:24 +03:00
			`(experimental)`

Fixed link to local scope Update the link to css-loader local scope 2017-02-18 05:56:56 +03:00			`When using [local scope CSS](https://github.com/webpack/css-loader#css-scope) the module exports the generated identifiers:`
added placeholders section to readme 2015-04-22 00:40:24 +03:00
Update README.md 2015-12-06 08:01:04 +03:00			``` javascript
Add -loader suffix to reflect new loader syntax webpack 2 requirement 2016-11-16 21:45:57 +03:00			`var style = require("style-loader!css-loader!./file.css");`
added placeholders section to readme 2015-04-22 00:40:24 +03:00			`style.placeholder1 === "z849f98ca812bc0d099a43e0f90184"`
			```

added ref-counted api fixes #4 2014-01-27 14:41:56 +04:00			`### Reference-counted API`

			``` javascript
Add -loader suffix to reflect new loader syntax webpack 2 requirement 2016-11-16 21:45:57 +03:00			`var style = require("style-loader/useable!css-loader!./file.css");`
added ref-counted api fixes #4 2014-01-27 14:41:56 +04:00			`style.use(); // = style.ref();`
			`style.unuse(); // = style.unref();`
			```

Update README.md 2015-12-06 08:01:04 +03:00			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`.
added ref-counted api fixes #4 2014-01-27 14:41:56 +04:00
			Note: Behavior is undefined when `unuse`/`unref` is called more often than `use`/`ref`. Don't do that.

Adds documentation of option 2014-10-20 20:26:18 +04:00			`### Options`

Updated readme to include documentation for insertAt parameter. 2015-07-07 22:14:22 +03:00			#### `insertAt`

finalized insertAt=top 2015-10-19 21:54:35 +03:00			By default, the style-loader appends `<style>` elements to the end of the `<head>` tag of the page. This will cause CSS created by the loader to take priority over CSS already present in the document head. To insert style elements at the beginning of the head, set this query parameter to 'top', e.g. `require('../style.css?insertAt=top')`.
Updated readme to include documentation for insertAt parameter. 2015-07-07 22:14:22 +03:00
Adds documentation of option 2014-10-20 20:26:18 +04:00			#### `singleton`

Replaced `#` with "number" 2015-06-19 02:00:39 +03:00			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 number of style tags allowed on a page. You can enable or disable it with the singleton query parameter (`?singleton` or `?-singleton`).
Adds documentation of option 2014-10-20 20:26:18 +04:00
feat(tag-attribute): Add support for custom tag attribute 2017-03-07 00:35:13 +03:00			#### `attrs`

			If defined, style-loader will attach given attributes with their values on `<style>` / `<link>` element.
			`Usage:`
			```javascript
			`require('style-loader?{attrs:{id: "style-tag-id"}}!style.scss');`

			`// will create style tag <style id="style-tag-id">`
			```

chore(readme): Update to webpack standard format 2017-01-11 18:49:17 +03:00			`### Recommended configuration`
added recommended configuration 2014-03-01 19:50:30 +04:00
Update README.md 2015-12-06 08:01:04 +03:00			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`).
added recommended configuration 2014-03-01 19:50:30 +04:00
			`So the recommended configuration for webpack is:`

			``` javascript
			`{`
			`module: {`
Change Readme to use new Rule.use configuration -A 2017-01-10 20:24:52 +03:00			`rules: [`
			`{`
			`test: /\.css$/,`
			`use: [`
			`{ loader: "style-loader" },`
			`{ loader: "css-loader" },`
			`],`
			`},`
			`{`
			`test: /\.useable\.css$/,`
			`use: [`
feat(tag-attribute): Add support for custom tag attribute 2017-03-07 00:35:13 +03:00			`{`
docs(readme): Update useable example (#184) 2017-03-08 17:27:27 +03:00			`loader: "style-loader/useable"`
Change Readme to use new Rule.use configuration -A 2017-01-10 20:24:52 +03:00			`},`
			`{ loader: "css-loader" },`
			`],`
			`},`
			`],`
			`},`
added recommended configuration 2014-03-01 19:50:30 +04:00			`}`
			```

Update README: set publicPath for ?sourceMap to load assets fixes #55 2015-06-30 23:25:43 +03:00			Note about source maps support and assets referenced with `url`: when style loader is used with ?sourceMap option, the CSS modules will be generated as `Blob`s, so relative paths don't work (they would be relative to `chrome:blob` or `chrome:devtools`). In order for assets to maintain correct paths setting `output.publicPath` property of webpack configuration must be set, so that absolute paths are generated.
Update README.md Add the install command for consistency with other webpack loader repos. 2014-10-17 14:55:36 +04:00
chore(readme): Update to webpack standard format 2017-01-11 18:49:17 +03:00			`<h2 align="center">Contributing</h2>`
Initial commit 2012-04-07 05:06:57 +04:00
chore(readme): Update to webpack standard format 2017-01-11 18:49:17 +03:00			Don't hesitate to create a pull request. Every contribution is appreciated. In development you can start the tests by calling `npm test`.

			`<h2 align="center">Maintainers</h2>`

			`<table>`
			`<tbody>`
			`<tr>`
			`<td align="center">`
			`<img width="150 height="150"`
			`src="https://avatars.githubusercontent.com/sokra?v=3">`
			`<br />`
			`<a href="https://github.com/">Tobias Koppers</a>`
			`</td>`
			`<td align="center">`
			`<img width="150 height="150"`
			`src="https://avatars.githubusercontent.com/SpaceK33z?v=3">`
			`<br />`
			`<a href="https://github.com/">Kees Kluskens</a>`
			`</td>`
			`<tr>`
			`<tbody>`
			`</table>`


			`<h2 align="center">LICENSE</h2>`

Remove license link To allow inclusion in https://webpack.js.org/ docs. 2017-02-04 23:15:52 +03:00			`MIT`
chore(readme): Update to webpack standard format 2017-01-11 18:49:17 +03:00
			`[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/style-loader.svg`
			`[deps-url]: https://david-dm.org/webpack/file-loader`

			`[chat]: https://badges.gitter.im/webpack/webpack.svg`
			`[chat-url]: https://gitter.im/webpack/webpack`