# postcss-svg-mixer

> PostCSS plugin for creating SVG sprites

Latest version **0.3.17** (published 2020-04-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install postcss-svg-mixer
pnpm add postcss-svg-mixer
yarn add postcss-svg-mixer
bun add postcss-svg-mixer
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.17 |
| Published | 2020-04-27 |
| First published | 2018-04-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 20.1 KB |
| Known vulnerabilities | 0 (+5 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 174 |
| Author | JetBrains |
| Maintainers | kisenka |
| Keywords | postcss, postcss-plugin, postcss plugin, svg, svg sprite |

## Links

- npm: https://www.npmjs.com/package/postcss-svg-mixer
- Repository: https://github.com/JetBrains/svg-mixer
- Homepage: https://github.com/JetBrains/svg-mixer/tree/master/packages/postcss-svg-mixer
- Issues: https://github.com/JetBrains/svg-mixer/issues
- npm.io page: https://npm.io/package/postcss-svg-mixer

## Dependencies (4)

- [postcss](https://npm.io/package/postcss.md) ^7.0.14
- [svg-mixer](https://npm.io/package/svg-mixer.md) ^2.3.14
- [query-string](https://npm.io/package/query-string.md) ^6.0.0
- [svg-mixer-utils](https://npm.io/package/svg-mixer-utils.md) ^0.3.4

## Recent versions

- 0.3.17 (latest) — 2020-04-27
- 0.3.16 — 2020-04-03
- 0.3.15 — 2020-04-01
- 0.3.13 — 2019-07-23
- 0.3.12 — 2019-04-27
- 0.3.11 — 2019-02-08
- 0.3.10 — 2018-12-05
- 0.3.9 — 2018-10-29
- 0.3.8 — 2018-10-29
- 0.3.7 — 2018-09-24
- 0.3.6 — 2018-08-20
- 0.3.5 — 2018-07-20
- 0.3.4 — 2018-06-18
- 0.3.3 — 2018-06-13
- 0.3.2 — 2018-05-11
- … 4 more at https://npm.io/package/postcss-svg-mixer/versions

## README

# postcss-svg-mixer

[PostCSS](https://github.com/postcss/postcss) plugin for creating SVG sprites.

## Table of contents

- [Demo](#demo)
- [Installation](#installation)
- [Usage](#usage)
  - [Via postcss.config.js](#via-postcss.config.js)
- [How it works](#how-it-works)
- [Configuration](#configuration)
  - [`spriteType`](#spriteType)
  - [`spriteFilename`](#spriteFilename)
  - [`match`](#match)
  - [`selector`](#selector)
  - [`userSprite`](#userSprite)

## Demo

Input
```css
.img {
  background: url('img.svg');
}
```

Output
```css
.img {
  background: url('sprite.svg') no-repeat 0 0;
  background-size: 100% 104.50%; /* Bg size calculated to scale image proportionally */
}
```

## Installation

```sh
npm install postcss-svg-mixer
```

## Usage

```js
const { writeFileSync } = require('fs');
const postcss = require('postcss');
const mixer = require('postcss-svg-mixer');

postcss()
  .use(mixer())
  .process('.img {background: url(img.svg)}')
  .then(result => {
    const msg = result.messages.find(m => m.kind === 'sprite');
    writeFileSync(msg.filename, msg.content);
  });
```

### Via postcss.config.js

```js
const mixer = require('postcss-svg-mixer');

module.exports = {
  plugins: [
    mixer()
  ]
}
```

## How it works

- Find `background` and `background-image` declarations which contains `url()` part.
- Trying to resolve file referenced in **first** `url()` occurrence. If URL starts 
  with tilde `~` plugin will search it in node_modules (Node.js `require.resolve` mechanism is used).
  If file exists - read it's content and add to sprite, throw error otherwise.
- Modify original background image declaration for properly positioning symbol on sprite canvas, eg:
  ```css
  .img {
    background: url('img.svg')
  }

  /* becomes */
  .img {
    background: url('sprite.svg') no-repeat 0 96.15%;
    background-size: 101.83% 217.01%;
  }
  ```
- Generate sprite and add a message to `result.messages` with sprite content, 
  filename and instance with following format:
  ```
  {
    type: string = 'asset',
    kind: string = 'sprite',
    plugin: string = 'postcss-svg-mixer',
    file: string,
    sprite: Sprite | StackSprite,
    filename: string,
    content: string
  }
  ```
  
## Configuration

<a id="spriteType"></a>
### `spriteType`

> Type: `string`<br>
> Default: `'classic'`

Possible values:
- `classic` (default). Images placed on canvas one after the other. Works perfect 
   in all browsers including IE10+. Generate additional styles for background image positioning.
- `stack`. [SVG stacking technique](https://css-tricks.com/svg-fragment-identifiers-work/#article-header-id-4) - 
   images placed one below the other and hidden by default. Target image becomes 
   visible via CSS `:target` selector when referencing sprite, eg. `sprite.svg#twitter`.
   **[Doesn't work in Safari](https://caniuse.com/#search=svg%20fragment)** prior to 
   11.1 macOS and 11.3 iOS. Don't generate additional styles for background image positioning.

<a id="match"></a>
### `spriteFilename`

> Type: `string`<br>
> Default: `'sprite.svg'`

Sprite filename which used in generated styles and in result message. 

<a id="match"></a>
### `match`

> Type: `string | RegExp | Array<string | RegExp>`<br>
> Default: `/\.svg(\?.*)?$/` (any SVG file with optional query param, eg `img.svg?qwe=123`)

Filter which images should be added to sprite. Could be a string (glob pattern), 
RegExp or array of them. Rules are tested against absolute image path. If URL 
starts with tilde `~` plugin will search image in node_modules (Node.js 
`require.resolve` mechanism is used).

<a id="selector"></a>
### `selector`

> Type: `string`<br>
> Default: `null`

By default plugin transforms current rule, but is is possible to create 
separate rule with sprite styles by specifying a valid CSS selector. Note that 
original background image declaration will be moved to new rule. Example:

```js
mixer({ selector: '::after' })
```

```css
/* Input */
.img {
  background: url('img.svg');
}

/* Output */
.img {}
.img::after {
  background: url('sprite.svg') no-repeat 0 0;
  background-size: 100% 104.50%;
}
```

<a id="userSprite"></a>
### `userSprite`

> Type: [`Sprite`](https://github.com/kisenka/svg-mixer/blob/master/packages/svg-mixer/lib/sprite.js) |
[`StackSprite`](https://github.com/kisenka/svg-mixer/blob/master/packages/svg-mixer/lib/stack-sprite.js)<br>
> Default: `null`

This plugin can be used as style generator for existing svg-mixer sprite instance.

```js
const { writeFileSync } = require('fs');
const createSprite = require('svg-mixer');
const postcssMixer = require('postcss-svg-mixer');

// Create sprite programmatically
createSprite('img/*.svg').then(result => {
  writeFileSync(result.filename, result.content);

  /**
   * Generate CSS code like
   * .img1 {background: url(img/img1.svg);}
   * .img2 {background: url(img/img2.svg);}
   */
  const cssInput = result.sprite.symbols
    .map(s => `.${s.id} {background: url(${s.image.path});}`)
    .join('\n');

  postcssMixer
    .process(cssInput, { from: __filename }, { userSprite: result.sprite })
    .then(({ css }) => writeFileSync('output.css', css));
});
``` 

## LICENSE

[MIT](https://github.com/JetBrains/svg-mixer/blob/master/LICENSE)

---
_Source: https://npm.io/package/postcss-svg-mixer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._