https://github.com/firefoxic/gulp-stacksvg
Combine svg files into one with stack method
https://github.com/firefoxic/gulp-stacksvg
gulp-plugin icon sprite stack svg
Last synced: about 2 months ago
JSON representation
Combine svg files into one with stack method
- Host: GitHub
- URL: https://github.com/firefoxic/gulp-stacksvg
- Owner: firefoxic
- License: mit
- Created: 2022-08-27T08:46:03.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-01T13:32:42.000Z (over 1 year ago)
- Last Synced: 2025-07-09T04:04:47.187Z (8 months ago)
- Topics: gulp-plugin, icon, sprite, stack, svg
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/gulp-stacksvg
- Size: 423 KB
- Stars: 16
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# gulp-stacksvg
[![License: MIT][license-image]][license-url]
[![Changelog][changelog-image]][changelog-url]
[![NPM version][npm-image]][npm-url]
[![Test Status][test-image]][test-url]
The gulp plugin to combine svg files into one using the stack method.
## Installation
```shell
pnpm add -D gulp gulp-stacksvg
```
## Usage
Add the following to your `gulpfile.js`:
```js
import { stacksvg } from "gulp-stacksvg"
import { dest, src } from "gulp"
export function createStack () {
return src(`./src/shared/icons/**/*.svg`)
.pipe(stacksvg())
.pipe(dest(`./dist/shared/icons`))
}
```
To combine all icons from `./src/shared/icons/` into the `./dist/shared/icons/stack.svg` run:
```shell
pnpm exec gulp createStack
```
## Why a stack?
Unlike all other methods for assembling a sprite, the stack does not limit us in choosing how to insert a vector into a page. Take a look at [the results](https://demos.frontend-design.ru/sprite/src/) of different ways to display fragments of different types of sprites.
We can use the stack in all four possible ways:
- in markup:
- in `src` of `img` tag — static,
- in the `href` of the `use` tag — with the possibility of repainting,
- in styles:
- in `url()` properties `background` — static,
- in `url()` properties `mask` — with the possibility of repainting.
[Demo page](https://firefoxic.github.io/gulp-stacksvg/example/) to prove it.
## Stack under the hood
This method was first mentioned in a Simurai [article](https://simurai.com/blog/2012/04/02/svg-stacks) on April 2, 2012. But even it uses unnecessarily complex code transformations.
This can be done much easier. In general, the stack is arranged almost like a symbol sprite, but without changing the icon tag (it remains the `svg` tag, as in the original icon files) and with the addition of a tiny bit of style.
```xml
:root svg:not(:target) { display: none }
```
```xml
```
```xml
```
```xml
```
```xml
```
The magic is in the stack inner style, which shows only the fragment requested by the link, hiding everything else:
```css
:root svg:not(:target) { display: none }
```
And now the icons from the external sprite are available in the styles
```html
Add to favorites
```
```css
.button {
display: inline-flex;
align-items: center;
gap: 0.5em;
&:hover {
--fill: red;
}
&::before {
content: "";
width: 1em;
height: 1em;
/* icon shape */
mask: var(--icon) no-repeat center / contain;
/* icon color */
background: var(--fill, orangered);
}
&:where(.button--icon_heart) {
--icon: url("../icons/stack.svg#heart");
}
}
```
For an icon inserted via `mask`, simply change the `background`. Moreover, unlike `use`, you can draw anything in the background under the mask, for example, a gradient.
## More info
- [SVG sprites: old-school, modern, unknown, and forgotten](https://pepelsbey.dev/articles/svg-sprites/#forgotten-stacks) by [Vadim Makeev](https://mastodon.social/@pepelsbey)
[license-url]: https://github.com/firefoxic/gulp-stacksvg/blob/main/LICENSE.md
[license-image]: https://img.shields.io/badge/License-MIT-limegreen.svg
[changelog-url]: https://github.com/firefoxic/gulp-stacksvg/blob/main/CHANGELOG.md
[changelog-image]: https://img.shields.io/badge/CHANGELOG-md-limegreen
[npm-url]: https://npmjs.com/package/gulp-stacksvg
[npm-image]: https://badge.fury.io/js/gulp-stacksvg.svg
[test-url]: https://github.com/firefoxic/gulp-stacksvg/actions
[test-image]: https://github.com/firefoxic/gulp-stacksvg/actions/workflows/test.yaml/badge.svg?branch=main