# Inline SVG

This module is the successor of [gulp-inline-svg](https://gitlab.sgalinski.de/toolchain/gulp-inline-svg), rewritten as a standalone library.

The purpose of this moudle is to pass it a location to a folder containing SVG icons and get back a string containing inline-svg codes that can be used as ```background-image```. The output can be customized with a mustache-template. By default it will return a string that can be saved as a Sass-partial, offering a mixin and variables for each icon. By providing your own template, you can customize the output any way you want, though.

## Compatibility

The generated SVG inline code is URL encoded, so it should be safe to use starting with IE 9.

## Important notes

The generated mixin contains width and height values for each SVG. Those values are taken from the width and height attribute inside the SVG. If it does not provide them, they will be set to 0px. You can still overwrite them in your CSS.

## Usage

### Install the inline-svg module

```bash
npm i @sgalinski/inline-svg
```

### Example for usage with Sass

```js
const InlineSvg = require('@sgalinsk/inline-svg');
const fs = require('fs');
(async () => {
    const sassTemplate = await new InlineSvg('./svgs');
    fs.writeFileSync('./_svg.scss', sassTemplate);
})();

```

#### Usage in Sass

Given you have an icon called ```icon-trash.svg```

```scss
@import 'svg';

.a-button--delete {
    @include inline-svg($icon-trash);
}
```

### Configuration

#### Use your own template

If you don't want to use the default Sass-template, you can esaily write your own and pass it as a configuration option:

```js
const InlineSvg = require('@sgalinsk/inline-svg');
const fs = require('fs');
(async () => {
    const sassTemplate = await new InlineSvg('./svgs', {
        template: './my-template.mustache'
    });
    fs.writeFileSync('./_svg.scss', sassTemplate);
})();
```

#### Pass additional variables

If needed, you can pass additional variables to the mustache template:

```js
const InlineSvg = require('@sgalinsk/inline-svg');
const fs = require('fs');
(async () => {
    const sassTemplate = await new InlineSvg('./svgs', {
        template: './my-template.mustache',
        context: {
            message: '// GENERATED BY gulpfile.js'
        }
    });
    fs.writeFileSync('./_svg.scss', sassTemplate);
})();
```

And then use it in your template:

```mustache
{{{message}}}

{{#svgs}}
${{{name}}}: "{{{inline}}}" {{width}} {{height}};
{{/svgs}}

@mixin inline-svg($name) {
    background: transparent url(nth($name, 1)) no-repeat 50% 50%;
    background-size: 100%;
    width: nth($name, 2);
    height: nth($name, 3);
}

@function inline-svg-width($name) {
    @return nth($name, 2);
}

@function inline-svg-height($name) {
    @return nth($name, 3);
}
```

#### Customize variables

If you want to use your own naming convention for the SVG-variables, you can pass an interceptor-function:

```js
const InlineSvg = require('@sgalinsk/inline-svg');
const fs = require('fs');
(async () => {
    const sassTemplate = await new InlineSvg('./svgs', {
        interceptor: function (svgData) {
            return Object.assign(svgData, { variableName: svgData.name.toLowerCase(), prefix: 'dso-icon' });
        }
    });
    fs.writeFileSync('./_svg.scss', sassTemplate);
})();
```