https://github.com/jannicz/svg-icon-sprite
A Web Component and a pattern for generating and including SVG spites
https://github.com/jannicz/svg-icon-sprite
Last synced: 3 months ago
JSON representation
A Web Component and a pattern for generating and including SVG spites
- Host: GitHub
- URL: https://github.com/jannicz/svg-icon-sprite
- Owner: jannicz
- Created: 2019-11-03T13:20:31.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-08-29T11:54:09.000Z (almost 5 years ago)
- Last Synced: 2025-03-18T14:44:15.379Z (3 months ago)
- Language: JavaScript
- Homepage: https://jannicz.github.io/svg-icon-sprite/
- Size: 565 KB
- Stars: 8
- Watchers: 1
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# SVG Icon Sprite - Web Component
A Web Component to include and manipulate SVGs from a generated sprite file
## Demo
[Try out the svg-icon-sprite demo](https://jannicz.github.io/svg-icon-sprite/)
## Use Cases
- Serve all your SVG icons from a single file
- Fill, scale and manipulate your icons
- Optionally, [generate the sprite file](#generating-the-sprite) using the provided CLI script
## Benefits
- dependency-free
- tiny 3KB (1.3KB gzipped)
- based on current web standards
## Import the component
### In static web pages
Simply reference the main file using the script tag in your HTML head
```html
```
### Via a module bundler
If you are using a bundler, import the node module via
```js
// Webpack or some ES6-style bundler
import 'svg-icon-sprite';
// Browserify (CommonJS)
const SvgIcon = require('svg-icon-sprite');
```
### Use the component
Now that the web component is registered, you can invoke using the `svg-icon` tag
```html
```
Above markup example will render the `explore` icon that is included in the
file `assets/sprites/sprite.svg` as a symbol - [read how to generate](#generating-the-sprite).
## Options
- `src` - source relative to your app folder, syntax is `folder/file#icon` where `icon` is the filename of the SVG
- `width` *optional* - width of the SVG in any length unit (i.e. `32px`, `50%`, `auto` etc.), default is `100%`
- `height` *optional* - the height of the SVG in any length unit
- `classes` *optional* - class name(s) separated by spaces
- `viewBox` *optional* - define lengths and coordinates in order to scale to fit the total space available
## Coloring
This icon pattern works best when applied on single color icons (SVGs that do not have
fill or stroke attributes). This enables you to use CSS rules to change the icon's color:
```scss
svg-icon {
color: red;
}
```
When used with icons that contain styles inside their markup (multi-color),
you will not be able to apply this CSS property without further [work](https://css-tricks.com/gotchas-on-getting-svg-into-production/#some-workarounds).
### Scaling and Sizing
If your SVG does not scale like expected (i.e. it is cropped or larger than desired) it might be lacking a `viewBox`.
Set the `viewBox` property manually to match the size of the exported shape. A combination of the correct
`viewBox` and width is required.
```html
```
See the viewBox [example](https://jannicz.github.io/svg-icon-sprite/examples/scaling.html) for further details.
Still troubled? Then read [this article](https://css-tricks.com/scale-svg/).
### Default sprite path
You can set the default sprite path by adding the attribute `data-svg-sprite-path` to any meta tag in your html head
```html
```
From now on you just need to pass the icon name as src attribute, i.e. `src="explore"`
## Integration
### Using inside of Angular or React
The SVG-Icon web component matches perfectly with SPA like Angular or React
- [React & Next.js integration example](./INTEGRATION.md#user-content-react)
- [Angular integration example](./INTEGRATION.md#user-content-angular)
## Polyfills and browser support
As Web Components are not supported in older browsers, you might want to install a polyfill
```
npm i @webcomponents/webcomponentsjs
```
and include it in the head of your `index.html`
```html
```
This should enable support in all evergreen browsers (also including Edge, Safari 9+).
To learn more, read [this](https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs#browser-support).
## Generating the sprite
Each time you add an icon, you need to run a script generating the sprite.
This module ships with a generator CLI script. It is recommended to add the
following line to your npm scripts
```json
"scripts": {
"generate:sprite": "svg-icon-generate --folder=dir/subdir --output=dir/filename.svg"
}
```
That lets you run the generator via
```
npm run generate:sprite
```
You can pass following arguments the form `=`
Parameter | Explanation | Default
---------- | ---------------------------------------- | -------
`--folder` | Path of the source folder relative to your *package.json* |
`--output` | Path and filename for the sprite output | `sprite.svg`
`--strip` | Whether to remove `fill` and `stroke` attributes | `false`
`--trim` | Whether to remove all whitespaces (tabs, linebreaks etc.) | `false`
Example usage
```
svg-icon-generate --folder=assets/icons --output=assets/sprites/sprite.svg --trim
```
The included script will iterate all SVGs in the source folder and create a single sprite SVG file
using the [symbols technique](https://css-tricks.com/svg-symbol-good-choice-icons/).
## Author & License
- Jan Suwart | MIT License