# svg-mixer

> Library for generating and transforming SVG sprites in modern way

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

## Install

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

## Health

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

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.3.14 |
| Published | 2020-04-27 |
| First published | 2018-04-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 15 |
| Unpacked size | 43.3 KB |
| Known vulnerabilities | 0 (+7 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 174 |
| Author | JetBrains |
| Maintainers | kisenka |
| Keywords | svg, svg sprite, svg stack |

## Links

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

## Dependencies (15)

- [he](https://npm.io/package/he.md) ^1.1.1
- [clone](https://npm.io/package/clone.md) ^2.1.2
- [pretty](https://npm.io/package/pretty.md) ^2.0.0
- [postcss](https://npm.io/package/postcss.md) ^6.0.21
- [postsvg](https://npm.io/package/postsvg.md) ^2.2.7
- [fs-extra](https://npm.io/package/fs-extra.md) ^5.0.0
- [glob-all](https://npm.io/package/glob-all.md) ^3.1.0
- [traverse](https://npm.io/package/traverse.md) ^0.6.6
- [url-slug](https://npm.io/package/url-slug.md) ^2.0.0
- [micromatch](https://npm.io/package/micromatch.md) 3.1.0
- [query-string](https://npm.io/package/query-string.md) ^6.0.0
- [merge-options](https://npm.io/package/merge-options.md) ^1.0.0
- [svg-mixer-utils](https://npm.io/package/svg-mixer-utils.md) ^0.3.4
- [posthtml-rename-id](https://npm.io/package/posthtml-rename-id.md) ^1.0.12
- [postcss-prefix-selector](https://npm.io/package/postcss-prefix-selector.md) ^1.6.0

## Recent versions

- 2.3.14 (latest) — 2020-04-27
- 2.3.13 — 2020-04-03
- 2.3.12 — 2020-04-01
- 2.4.0 — 2019-07-23
- 2.3.9 — 2019-05-08
- 2.3.8 — 2019-02-08
- 2.3.7 — 2018-12-05
- 2.3.6 — 2018-10-29
- 2.3.5 — 2018-10-29
- 2.3.4 — 2018-09-24
- 2.3.3 — 2018-08-20
- 2.3.2 — 2018-07-20
- 2.3.1 — 2018-06-18
- 2.3.0 — 2018-06-13
- 2.2.0 — 2018-05-11
- … 2 more at https://npm.io/package/svg-mixer/versions

## README

# SVG Mixer

Library for generating and transforming SVG sprites in modern way.

## Table of contents

- [Quick example](#quick-example)
- [Installation](#installation)
- [Adapters](#adapters)
- [Configuration](#configuration)
  - [`spriteType`](#spriteType)
  - [`spriteConfig`](#spriteConfig)
  - [`generateSymbolId`](#generateSymbolId)
  - [`prettify`](#prettify)
  - [`spriteClass`](#spriteClass)
  - [`symbolClass`](#symbolClass)
- [API](#api)
- [Extending](#extending)

## Quick example

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

mixer('img/*.svg')
  .then(result => console.log(result.content));

// Write sprite content on disk
mixer(['img/**/*.svg', '!img/raw/**'])
  .then(result => result.write('sprite.svg'));

// 'Stack' sprite
mixer('img/**/*.svg', { spriteType: 'stack' })
  .then(result => result.write('sprite.svg'));

// Classic sprite with empty canvas and <defs> section with symbols
// Useful for inlining directly in HTML markup and refer to images via <use xlink:href="#symbol-id" />
mixer('img/**/*.svg', { spriteConfig: { usages: false } })
  .then(result => result.write('sprite.svg'));
```

## Installation

```bash
npm install svg-mixer
```

## Adapters

- PostCSS: [postcss-svg-mixer](https://github.com/kisenka/svg-mixer/tree/master/packages/postcss-svg-mixer).
- Gulp: [gulp-svg-mixer](https://github.com/kisenka/svg-mixer/tree/master/packages/gulp-svg-mixer).

## 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+. If sprite embedded in CSS - requires some 
   additional styles for background image positioning. [postcss-svg-mixer](https://github.com/kisenka/svg-mixer/tree/master/packages/postcss-svg-mixer) 
   can be used to generate such styles.
- `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)** (both desktop and mobile) 
   prior to 11.1 macOS and 11.3 iOS. Don't requires any styles when embedding.

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

> Type: `Object`

Fine tune sprite output.

- `filename` (default: `'sprite.svg'`). Sprite file name.
- `attrs` (default: `{}`). Additional sprite SVG attributes, eg. `{ class: 'my-sprite' }`.
- `usages` (default: `true`). Render images on sprite canvas or just place their symbols in
  `<defs>` section. It's useful to set `false` when sprite inlined directly to HTML 
  markup and symbols are referenced via `<use xlink:href="#symbol-id" />`. 
  Make sense only for classic sprite
- `spacing` (default: `10`). Spacing between symbols in pixels. Make sense only for classic sprite 

Stack sprite also has following options:
- `usageClassName` (default: `sprite-symbol-usage`). CSS classname of symbol to set.
  Needed to avoid possible conflicts between sprite and symbol styles.
- `styles` (default: see [stack-sprite](lib/stack-sprite.js)). CSS to archive stack technique. 
  Will be placed in `<defs>` section.

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

> Type: `function(path: string, query: string = '') => string`

Function to generate `<symbol id>` attribute. By default file name without extension is used.
Accepts 2 arguments: absolute path to file and optional query string.

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

> Type: `boolean`<br>
> Default: `false`

Prettify sprite output.

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

Custom sprite implementation. See [extending](#extending) section.

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

Custom sprite symbol implementation. See [extending](#extending) section.

## API

### Main function

Main function accepts 2 arguments: glob pattern and config.
Glob pattern could be string or array of strings. Relative/absolute path to file is also allowed:

```js
mixer('img/*.svg');
mixer(['img/*.svg', '!img/raw/*.svg']); // all from img/, but not from img/raw/
mixer(['img/*.svg', 'path/to/file', '/absolute/path/to/file']);
```

### Result

Result is an object with `content` and `filename` fields, and `write()` method:
```
Result<{
  content: string,
  filename: string,
  write(filepath: string) => Promise
}>
```

The rest API docs will be ASAP. For now check [TypeScript definitions](svgmixer.d.ts) and source :)

## Extending 

svg-mixer offers OOP-like extending mechanism - to write custom sprite or symbol 
transformation you'll need to extend a base class and override `generate` method,
which returns promise resolved with [postsvg.tree](https://github.com/kisenka/svg-mixer/tree/master/packages/postsvg#tree).

Example: add `class="my-super-class"` to each node in generated sprite.

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

class MySprite extends mixer.Sprite {
  generate() {
    // Call parent `generate` method and then transform the tree
    return super.generate().then(svg => {
      svg.each(node => node.attrs.class = 'my-super-class');
      return svg;
    });
  }
}

mixer('img/*.svg', { spriteClass: MySprite });
```

As it possible to pass query params when adding image to sprite by `addSymbolFromFile` 
compiler method, it makes possible to process single file with different params 
in various ways (like webpack does).

Example: fill one image with different colors.

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

class MySymbol extends mixer.SpriteSymbol {
  generate() {
    const { query } = this.image;
    return super.generate().then(svg => transform(query)(svg));
  }
}

const compiler = new mixer.Compiler({ symbolClass: MySymbol });
compiler
  .addSymbolFromFile('img.svg')
  .then(() => compiler.addSymbolFromFile('img.svg?fill=red'))
  .then(() => compiler.compile())
  .then(result => console.log(result.content));
```

The code above will generate sprite with 2 symbols - original image and filled with red color.
In this example adding images and generating sprite performed manually, but when 
using svg-mixer [adapters](#adapters) you'll need only to pass custom implementation 
to adapter config.

## LICENSE

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

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