README.md 2.53 KB
Newer Older
1 2 3
# gulp-inline-svg
> inline-svg plugin for [gulp](https://github.com/wearefractal/gulp)

Guy Tepper's avatar
Guy Tepper committed
4
This plugin takes a couple of SVG files and provides them inside a Sass mixin as inlined background-images. By doing so, you can use them without having to touch your markup.
5 6

## Compatibility
7
The inlined SVG gets URL encoded, so it's safe to use starting with IE9.
8 9 10 11 12 13

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

Guy Tepper's avatar
Guy Tepper committed
14
First, install `gulp-inline-svg` as a development dependency:
15 16 17 18 19 20 21 22 23 24 25

```shell
npm install --save-dev gulp-inline-svg
```

Then, add it to your `gulpfile.js`. I'd recommend to use it in conjunction with [gulp-svgmin](https://www.npmjs.com/package/gulp-svgmin) to clean the SVG before inlining them.

```javascript
var inlineSvg = require("gulp-inline-svg"),
	svgMin = require('gulp-svgmin');

Guy Tepper's avatar
Guy Tepper committed
26 27 28 29
gulp.task('inline-svg', function() {
	return gulp.src("images/svgs/**/*.svg")
		.pipe(svgMin())
		.pipe(inlineSvg())
30
		.pipe(gulp.dest("sass"));
Guy Tepper's avatar
Guy Tepper committed
31
});
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
```

This will create a _svg.scss file inside your 'sass' folder.

### Usage inside you Sass code
The _svg.scss file will provide you with the following mixins and functions:

#### inline-svg mixin

```scss
.my-icon {
	// will set the svg as background-image and width/height
	@include inline-svg($icon-name);
}
```

#### inline-svg-width function

```scss
.my-icon {
	margin-left: inline-svg-width($icon-name);
}
```

#### inline-svg-height function

```scss
.my-icon {
	margin-bottom: inline-svg-height($icon-name);
}
```

## Configuration
Guy Tepper's avatar
Guy Tepper committed
65
If you want to customize the default configuration, you can pass an options object to the task function:
66

Philipp Nowinski's avatar
Philipp Nowinski committed
67
```javascript
68
gulp.src("images/svgs/**/*.svg")
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
	.pipe(svgMin())
	.pipe(inlineSvg({
		filename: '_svg-file.scss',
		template: 'mytemplate.mustache'
	}))
	.pipe(gulp.dest("sass"));
```

### filename
Specifies the name of the generated file.

### template
The plugin will generate an .scss-file by default, but you can easily adopt this for other languages, by using your own template. With this option, you can specify the path to a [mustache](https://github.com/janl/mustache.js/) template.

You can use the default template as a blueprint to create your own. And please don't hesitate to [share](http://gitlab.sgalinski.de/toolchain/gulp-inline-svg/fork/new) your template if you create one for an additional language.

## License

[MIT License](http://en.wikipedia.org/wiki/MIT_License)