SVG icon sprite component for Angular 17+

This library provides both a solution for generating SVG sprites and a module for including them.

Demo

Try out the ng-svg-icon-sprite demo

Use Cases

- include single-color icons from a sprite
- fill and scale icons dynamically via CSS (i.e. hover, focus effects)
- meet accessibility requirements for inline SVGs

Installation

After installing the package as dependency you can import it into
any application’s app.module.ts by simply including it in its @NgModule imports array:

``javascript
import { IconSpriteModule } from 'ng-svg-icon-sprite'; // <-- here

@NgModule({
declarations: [
AppComponent
],
imports: [
BrowserModule,
IconSpriteModule // <-- here
],
bootstrap: [AppComponent]
})
export class AppModule { }
`

Usage

To use your SVGs from a sprite you need to:

1. Convert your SVG icons into a sprite using a script
2. Include the svg-icon-sprite component with the sprite path, and the icon name

$3

First add the library for sprite generation svg2sprite as a devDependency:

`json
"devDependencies": {
"svg2sprite-cli": "^2.0.1"
}
`

Each time you add an icon, you need to run the script generating the sprite. You might want to add it to your npm scripts:

`json
"scripts": {
"generate:svg-sprite": "svg2sprite ./src/assets/icons ./src/assets/sprites/sprite.svg --stripAttrs fill --stripAttrs stroke --stripAttrs id"
}
`

now execute the script:

`bash
npm run generate:svg-sprite
`

__Note: only if the fill and stroke attributes are removed, the SVG can be styled via CSS. If don't need to apply color changes on your icons,
go for the multi-color pattern described below__

The script will take all SVG icons under src/app/assets/icons and create a sprite SVG into
src/app/assets/sprites using the svg symbols technique:

`bash
app
└── assets
└── icons (icons source)
└── icon-1.svg
└── icon-2.svg
└── sprites (sprite destination)
└── sprite.svg
`

$3

Now you can include icons by using the svg-icon-sprite component directive:

`html

[src]="'assets/sprites/sprite.svg#cart'"
[width]="'22px'"
[classes]="'my-icon-class'"
>
`

Having a dynamic icon name:

`html

`

Options

- src - icon source name, the syntax is path/file#icon where path is relative to app folder, file is
the name of the sprite and icon is the filename of the svg icon.
- 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, if undefined height will equal the width
- classes optional - class name(s) for this icon, default is icon
- viewBox optional - define lengths and coordinates in order to scale to fit the total space available (use for scaling)
- preserveAspectRatio optional - manipulate the aspect ratio, only in combination with viewBox
- title - optional - text string that will be rendered into a title tag as the first child of the SVG node
- attribute - optional - tuple or array of tuples containing key/value pair that should be added as an attribute on the SVG node, i.e. "['aria-hidden', 'true']" becomes

Styling

In order to change the icon color, add a CSS color property to the component invoking svg-icon-sprite. The SVG component uses
the currentColor value to pass the ancestor's color through to the SVG shapes:

`css
/ host component styles /
color: red;
`

Advanced Configuration

$3

If you have another asset folder structure, set your input and output path in the npm script:

`bash
svg2sprite sourcefolder destination/filename.svg
`

$3

If your SVG does not scale like expected (i.e. it is cropped or larger than desired) it might be lacking a viewBox.
You need to set the viewBox attributes manually to match the size of the exported shape. A combination of the correct
viewBox and width is required. Add the viewBox attribute and decrease/increase the last 2 values:

`html

[src]="'assets/sprites/sprite.svg#star'"
[width]="'40px'"
[viewBox]="'0 0 80 80'"
>
`

See the viewBox example for further details.
Still having trouble with scaling or sizing? Read this article about SVG scaling.

$3

If you wish use SVGs that contain inline styles (multi-color) that do not need to be overridden by CSS,
provide a separate sprite file that keeps the stroke and fill attributes:

`json
"scripts": {
"generate:svg-multicolor-sprite": "svg2sprite ./src/assets/svg-images ./src/assets/sprites/image-sprite.svg"
}
`

The generated sprite will preserve its original styles, but you won't be able to style it via CSS that easily (demo).

$3

If your app uses one sprite source, you can set its path in your @NgModule imports array:

`javascript
imports: [
IconSpriteModule.forRoot({ path: 'assets/sprites/sprite.svg' })
]
`

You can now leave out the path and just provide the icon name (demo).

`html

`

Doing so you will still be able to override the default path by using the full syntax for particular icons that should use a different sprite file.

Browser Support

- Chrome (63)
- Firefox (57)
- Safari 11
- Edge

Accessibility

In order to support screen readers and make the icons meaningful, you can use following patters:

- add a title with descriptive text (demo)
- optionally reference the title node using aria-labelledby=”icon-title”
- optionally set the node's role to image (role=”img”)

`html
[src]="'assets/sprites/sprite.svg#star'"
[title]="'Some title text'"
[attribute]="[['aria-labelledby', 'star-title'], ['role', 'img']]"
>
`

If you want to prevent the icon from being accessed by screen readers (i.e if you already have a descriptive text somewhere else),
set the attribute of ['aria-hidden', 'true']` instead.

Or use combinations of several methods to achieve better results, like described in this article.

Compatibility

This library is optimized for Angular 17+. If you combine multiple frameworks (i.e. React, Vue, etc.), it is recommended to use svg-icon-sprite web component instead!

Author & License

- Jan Suwart | MIT License