{"id":13497082,"url":"https://github.com/jannicz/ng-svg-icon-sprite","last_synced_at":"2025-03-20T07:41:49.733Z","repository":{"id":27931771,"uuid":"115614820","full_name":"jannicz/ng-svg-icon-sprite","owner":"jannicz","description":"Angular 16+ package for generating and using inline SVG icons in your project","archived":false,"fork":false,"pushed_at":"2024-05-06T18:49:24.000Z","size":6137,"stargazers_count":58,"open_issues_count":4,"forks_count":12,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-03T15:18:32.233Z","etag":null,"topics":["angular","generates-sprites","inline-svg","svg-component","svg-icons","svg-sprites","svg-symbols"],"latest_commit_sha":null,"homepage":"https://jannicz.github.io/ng-svg-icon-sprite/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jannicz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-28T11:01:12.000Z","updated_at":"2024-09-03T08:37:31.000Z","dependencies_parsed_at":"2024-01-16T09:55:39.921Z","dependency_job_id":"cc0a40f1-5141-426a-aad3-9e473aec63c4","html_url":"https://github.com/jannicz/ng-svg-icon-sprite","commit_stats":{"total_commits":72,"total_committers":6,"mean_commits":12.0,"dds":"0.33333333333333337","last_synced_commit":"eb42a1fad681393b5ff9a782d3f4f84b9b079bfd"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jannicz%2Fng-svg-icon-sprite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jannicz%2Fng-svg-icon-sprite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jannicz%2Fng-svg-icon-sprite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jannicz%2Fng-svg-icon-sprite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jannicz","download_url":"https://codeload.github.com/jannicz/ng-svg-icon-sprite/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244574787,"owners_count":20474818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","generates-sprites","inline-svg","svg-component","svg-icons","svg-sprites","svg-symbols"],"created_at":"2024-07-31T20:00:22.910Z","updated_at":"2025-03-20T07:41:49.704Z","avatar_url":"https://github.com/jannicz.png","language":"TypeScript","funding_links":[],"categories":["Uncategorized","Table of contents"],"sub_categories":["Uncategorized","Third Party Components"],"readme":"# SVG icon sprite component for Angular 17+\n\nThis library provides both a solution for generating SVG sprites and a [module](https://www.npmjs.com/package/ng-svg-icon-sprite) for including them.\n\n## Demo\n\n\u003cimg width=\"280\" alt=\"Demo gif animation\" src=\"svg-icon-sprite-anim.gif\"\u003e\n\n[Try out the ng-svg-icon-sprite demo](https://jannicz.github.io/ng-svg-icon-sprite/)\n\n## Use Cases\n\n- include single-color icons from a sprite\n- fill and scale icons dynamically via CSS (i.e. hover, focus effects)\n- meet accessibility requirements for inline SVGs\n\n## Installation\n\nAfter installing the package as dependency you can import it into\nany application’s `app.module.ts` by simply including it in its `@NgModule` imports array:\n\n```javascript\nimport { IconSpriteModule } from 'ng-svg-icon-sprite'; // \u003c-- here\n\n@NgModule({\n  declarations: [\n    AppComponent\n  ],\n  imports: [\n    BrowserModule,\n    IconSpriteModule // \u003c-- here\n  ],\n  bootstrap: [AppComponent]\n})\nexport class AppModule { }\n```\n\n## Usage\n\nTo use your SVGs from a sprite you need to:\n\n1. Convert your SVG icons into a sprite using a script\n2. Include the `svg-icon-sprite` component with the sprite path, and the icon name\n\n### Step 1: Generate the sprite\n\nFirst add the library [for sprite generation svg2sprite](https://github.com/mrmlnc/svg2sprite-cli) as a devDependency:\n                                                                                      \n```json\n\"devDependencies\": {\n  \"svg2sprite-cli\": \"^2.0.1\"\n}\n```\n\nEach time you add an icon, you need to run the script generating the sprite. You might want to add it to your npm scripts:\n\n```json\n\"scripts\": {\n  \"generate:svg-sprite\": \"svg2sprite ./src/assets/icons ./src/assets/sprites/sprite.svg --stripAttrs fill --stripAttrs stroke --stripAttrs id\"\n}\n```\n\nnow execute the script:\n\n```bash\nnpm run generate:svg-sprite\n```\n\n__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,\ngo for the multi-color pattern [described below](#user-content-dealing-with-multi-color-svgs-containing-inline-styles)__\n\nThe script will take all SVG icons under `src/app/assets/icons` and create a sprite SVG into\n`src/app/assets/sprites` using the [svg symbols technique](https://css-tricks.com/svg-symbol-good-choice-icons/):\n\n```bash\napp\n└── assets\n    └── icons (icons source)\n        └── icon-1.svg\n        └── icon-2.svg\n    └── sprites (sprite destination)\n        └── sprite.svg\n```\n\n### Step 2: Use the component\n\nNow you can include icons by using the `svg-icon-sprite` component directive:\n\n```html\n\u003c!-- include the icon named 'cart' --\u003e\n\u003csvg-icon-sprite\n  [src]=\"'assets/sprites/sprite.svg#cart'\"\n  [width]=\"'22px'\"\n  [classes]=\"'my-icon-class'\"\n\u003e\u003c/svg-icon-sprite\u003e\n```\n\nHaving a dynamic icon name:\n\n```html\n\u003csvg-icon-sprite [src]=\"'assets/sprites/sprite.svg#' + iconName\"\u003e\u003c/svg-icon-sprite\u003e\n```\n\n## Options\n\n- `src` - icon source name, the syntax is `path/file#icon` where `path` is relative to app folder, `file` is\nthe name of the sprite and `icon` is the filename of the svg icon.\n- `width` *optional* - width of the svg in any length unit, i.e. `32px`, `50%`, `auto` etc., default is `100%`\n- `height` *optional* - the height of the svg in any length unit, if undefined height will equal the width\n- `classes` *optional* - class name(s) for this icon, default is `icon`\n- `viewBox` *optional* - define lengths and coordinates in order to scale to fit the total space available (use for scaling)\n- `preserveAspectRatio` *optional* - manipulate the aspect ratio, only in combination with `viewBox`\n- `title` - *optional* - text string that will be rendered into a title tag as the first child of the SVG node\n- `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 `\u003csvg aria-hidden=\"true\"\u003e`\n\n## Styling\n\nIn order to change the icon color, add a CSS `color` property to the component invoking svg-icon-sprite. The SVG component uses\nthe `currentColor` value to [pass the ancestor's color](https://css-tricks.com/cascading-svg-fill-color) through to the SVG shapes:\n\n```css\n/* host component styles */\ncolor: red;\n```\n\n## Advanced Configuration\n\n### Assets folder\n\nIf you have another asset folder structure, set your input and output path in the npm script:\n\n```bash\nsvg2sprite sourcefolder destination/filename.svg\n```\n\n### Scaling and Sizing\n\nIf your SVG does not scale like expected (i.e. it is cropped or larger than desired) it might be lacking a `viewBox`.\nYou need to set the `viewBox` attributes manually to match the size of the exported shape. A combination of the correct\n`viewBox` and width is required. Add the `viewBox` attribute and decrease/increase the last 2 values:\n\n```html\n\u003c!-- i.e. lower '0 0 80 80' to '0 0 40 40' to scale up/down --\u003e\n\u003csvg-icon-sprite\n  [src]=\"'assets/sprites/sprite.svg#star'\"\n  [width]=\"'40px'\"\n  [viewBox]=\"'0 0 80 80'\"\n\u003e\u003c/svg-icon-sprite\u003e\n```\n\nSee the viewBox [example](https://jannicz.github.io/ng-svg-icon-sprite/#viewBox) for further details.\nStill having trouble with scaling or sizing? Read [this article](https://css-tricks.com/scale-svg/) about SVG scaling.\n\n### Dealing with multi color SVGs containing inline styles\n\nIf you wish use SVGs that contain inline styles (multi-color) that do not need to be overridden by CSS,\nprovide a separate sprite file that keeps the stroke and fill attributes:\n\n```json\n\"scripts\": {\n  \"generate:svg-multicolor-sprite\": \"svg2sprite ./src/assets/svg-images ./src/assets/sprites/image-sprite.svg\"\n}\n```\n\nThe generated sprite will preserve its original styles, but you won't be able to style it via CSS that easily ([demo](https://jannicz.github.io/ng-svg-icon-sprite/#multicolor)).\n\n### Setting a default sprite path for all icons\n\nIf your app uses one sprite source, you can set its path in your `@NgModule` imports array:\n\n```javascript\nimports: [\n  IconSpriteModule.forRoot({ path: 'assets/sprites/sprite.svg' })\n]\n```\n\nYou can now leave out the path and just provide the icon name ([demo](https://jannicz.github.io/ng-svg-icon-sprite/#defaultpath)).\n\n```html\n\u003csvg-icon-sprite [src]=\"'star'\"\u003e\u003c/svg-icon-sprite\u003e\n```\n\nDoing 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.\n\n## Browser Support\n\n- Chrome (63)\n- Firefox (57)\n- Safari 11\n- Edge\n\n## Accessibility\n\nIn order to support screen readers and make the icons meaningful, you can use following patters:\n\n- add a `title` with descriptive text ([demo](https://jannicz.github.io/ng-svg-icon-sprite/#a11y))\n- optionally reference the title node using `aria-labelledby=”icon-title”`\n- optionally set the node's `role` to image (`role=”img”`)\n\n```html\n\u003csvg-icon-sprite\n  [src]=\"'assets/sprites/sprite.svg#star'\"\n  [title]=\"'Some title text'\"\n  [attribute]=\"[['aria-labelledby', 'star-title'], ['role', 'img']]\"\n\u003e\u003c/svg-icon-sprite\u003e\n```\n\nIf you want to prevent the icon from being accessed by screen readers (i.e if you already have a descriptive text somewhere else),\nset the `attribute` of `['aria-hidden', 'true']` instead.\n\nOr use combinations of several methods to achieve better results, like described in this [article](https://css-tricks.com/accessible-svgs/).\n\n## Compatibility\n\nThis 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](https://www.npmjs.com/package/svg-icon-sprite) instead!\n\n## Author \u0026 License\n\n- Jan Suwart | MIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjannicz%2Fng-svg-icon-sprite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjannicz%2Fng-svg-icon-sprite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjannicz%2Fng-svg-icon-sprite/lists"}