{"id":13808644,"url":"https://github.com/push-based/ngx-fast-svg","last_synced_at":"2025-04-05T18:06:00.746Z","repository":{"id":37095637,"uuid":"480570586","full_name":"push-based/ngx-fast-svg","owner":"push-based","description":"📦 SVGs, fast and developer friendly in Angular","archived":false,"fork":false,"pushed_at":"2024-10-13T11:22:44.000Z","size":8394,"stargazers_count":56,"open_issues_count":9,"forks_count":5,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-10-24T23:28:15.199Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/push-based.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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},"funding":{"github":["push-based","BioPhoton"]}},"created_at":"2022-04-11T22:23:08.000Z","updated_at":"2024-10-17T21:06:22.000Z","dependencies_parsed_at":"2023-11-21T15:30:25.886Z","dependency_job_id":"6c6c725d-7f29-40d6-8262-343b599f2822","html_url":"https://github.com/push-based/ngx-fast-svg","commit_stats":{"total_commits":218,"total_committers":11,"mean_commits":"19.818181818181817","dds":0.6926605504587156,"last_synced_commit":"376a952446f8be13c48f5eb557dc708ee0b063a0"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/push-based%2Fngx-fast-svg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/push-based%2Fngx-fast-svg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/push-based%2Fngx-fast-svg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/push-based%2Fngx-fast-svg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/push-based","download_url":"https://codeload.github.com/push-based/ngx-fast-svg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378140,"owners_count":20929296,"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":[],"created_at":"2024-08-04T01:01:47.971Z","updated_at":"2025-04-05T18:06:00.719Z","avatar_url":"https://github.com/push-based.png","language":"TypeScript","funding_links":["https://github.com/sponsors/push-based","https://github.com/sponsors/BioPhoton"],"categories":["Third Party Components"],"sub_categories":["Icons"],"readme":"# ngx-fast-svg\n\nFast SVG's for Angular powered by browser native features with best performance practices and DX in mind.\n\n## Why another SVG lib for Angular?\n\nCurrent implementations of SVG handling in the Browser lacks of awareness of performance.\n\nThis library covers next aspects that developers should consider for their projects:\n\n- Image loading performance\n- Initial rendering performance and runtime performance\n- SVG reusability\n- Optimized bundle size\n- SSR\n- Edge ready (only edge safe APIs are used)\n\n## Getting started\n\n### Install\n\n```bash\nnpm install @push-based/ngx-fast-svg --save\n# or\nyarn add @push-based/ngx-fast-svg\n```\n\n### Setup\n\n#### Setup the library in your standalone application:\n\n**main.ts**\n\n```typescript\nimport { provideFastSVG } from '@push-based/ngx-fast-svg';\n\nbootstrapApplication(AppComponent, {\n  providers: [\n    // ... other providers\n    provideFastSVG({\n      url: (name: string) =\u003e `path/to/svg-assets/${name}.svg`,\n    })\n  ]\n});\n```\n\n#### Setup the library in your Angular application using NgModules:\n\n**app.module.ts**\n\n```typescript\n// ...\nimport { provideFastSVG } from '@push-based/ngx-fast-svg';\n\n@NgModule({\n  declarations: [AppComponent],\n  providers: [\n    provideFastSVG({\n      url: (name: string) =\u003e `path/to/svg-assets/${name}.svg`,\n    })\n  ],\n  bootstrap: [AppComponent]\n})\nexport class AppModule {}\n```\n\nor if you're using an older version of the library, you can still do:\n\n```typescript\n// ...\nimport { FastSvgModule } from '@push-based/ngx-fast-svg';\n\n@NgModule({\n  declarations: [AppComponent],\n  imports: [\n    FastSvgModule.forRoot({\n      url: (name: string) =\u003e `path/to/svg-assets/${name}.svg`,\n    })\n  ],\n  providers: [],\n  bootstrap: [AppComponent]\n})\nexport class AppModule {}\n```\n\n### Usage in the template\n\n```html\n\u003cfast-svg [name]=\"svgName\" [size]=\"svgSize\"\u003e\u003c/fast-svg\u003e\n\u003c!-- OR --\u003e\n\u003cfast-svg [name]=\"svgName\" [width]=\"svgWidth\" [height]=\"svgHeight\"\u003e\u003c/fast-svg\u003e\n```\n\n### Advanced usage\n\n#### Providing additional options\n\nDuring setup phase you can provide additional optional settings such as:\n\n```typescript\n  defaultSize?: string;\n  suspenseSvgString?: string;\n  svgLoadStrategy?: Type\u003cSvgLoadStrategy\u003e;\n```\n\n`svgLoadStrategy` can be any injectable class that has `config` that excepts method that accepts url and returns observable string,\nand `load` which accepts the configured url as an observable and returns the svg as an observable string.\n\n```typescript\n@Injectable()\nexport abstract class SvgLoadStrategy {\n  abstract load(url: string): Observable\u003cstring\u003e;\n}\n```\n\n**app.module.ts**\n\n```typescript\n// ...\nimport { FastSvgModule } from '@push-based/ngx-fast-svg';\nimport { loaderSvg } from './assets';\nimport { HttpClientFetchStrategy } from './fetch-strategy';\n\n@NgModule({\n  declarations: [AppComponent],\n  imports: [\n    FastSvgModule.forRoot({\n      url: (name: string) =\u003e `path/to/svg-assets/${name}.svg`,\n      defaultSize: '32',\n      suspenseSvgString: loaderSvg,\n      svgLoadStrategy: HttpClientFetchStrategy\n    })\n  ],\n  providers: [],\n  bootstrap: [AppComponent]\n})\nexport class AppModule {}\n```\n\nor in a standalone application:\n\n**main.ts**\n\n```typescript\nimport { provideFastSVG } from '@push-based/ngx-fast-svg';\nimport { loaderSvg } from './assets';\nimport { HttpClientFetchStrategy } from './fetch-strategy';\n\nbootstrapApplication(AppComponent, {\n  providers: [\n    // ... other providers\n    provideFastSVG({\n      url: (name: string) =\u003e `path/to/svg-assets/${name}.svg`,\n      defaultSize: '32',\n      suspenseSvgString: loaderSvg,\n      svgLoadStrategy: HttpClientFetchStrategy\n    })\n  ]\n});\n```\n\n#### SSR Usage\n\nYou can provide your own SSR loading strategy that can look like this:\n\n```typescript\n@Injectable()\nexport class SvgLoadStrategySsr implements SvgLoadStrategy {\n  load(url: string): Observable\u003cstring\u003e {\n    const iconPath = join(process.cwd(), 'dist', 'app-name', 'browser', url);\n    const iconSVG = readFileSync(iconPath, 'utf8');\n    return of(iconSVG);\n  }\n}\n```\n\nAnd then just provide it in you server module.\n\n**app.server.module.ts**\n\n```typescript\n@NgModule({\n  declarations: [],\n  imports: [\n    AppModule,\n    ServerModule,\n    ServerTransferStateModule,\n  ],\n  providers: [\n    provideFastSVG({\n      svgLoadStrategy: SvgLoadStrategySsr,\n      url: (name: string) =\u003e `assets/svg-icons/${name}.svg`,\n    }),\n  ],\n  bootstrap: [AppComponent],\n})\nexport class AppServerModule {}\n```\n\n#### Providing a lazy configuration\n\nIf you need to provide a lazy configuration you can use the config method in the `SvgLoadStrategy`:\n\n```typescript\n@Injectable()\nclass LazyConfigSvgLoadStrategy extends SvgLoadStrategyImpl {\n  dummyLazyConfig$ = timer(5_000).pipe(map(() =\u003e 'assets/svg-icons'))\n  override config(url: string): Observable\u003cstring\u003e {\n    return this.dummyLazyConfig$.pipe(map((svgConfig) =\u003e `${svgConfig}/${url}`));\n  }\n}\n```\n\nAnd pass it to the provider function:\n\n```typescript\nimport { provideFastSVG } from '@push-based/ngx-fast-svg';\n\nbootstrapApplication(AppComponent, {\n  providers: [\n    // ... other providers\n    provideFastSVG({\n      url: (name: string) =\u003e `${name}.svg`,\n      svgLoadStrategy: LazyConfigSvgLoadStrategy,\n    })\n  ]\n});\n```\n\n## Features\n\n### :sloth: Lazy loading for SVGs\n\nLazy loading is referring to loading resources only if they are visible on screen. Like lazy loading imgs.\nIt can be implemented natively over loading attribute or over viewportobserver.\nThis library supports lazy loading for SVGs using purely browser native features.\n\n- We display an empty SVG at the beginning. Invisible and without dimensions.\n- On View init the size is applied even if no svg is loaded to avoid flickering in dimensions.\n- A suspense svg is displayed at the same time to reduce visual flickering.\n- We use an img element here to leverage the browsers native features:\n  - Lazy loading (loading=\"lazy\") to only load the svg that are actually visible\n  - The image is styled with display none. this prevents any loading of the resource ever.\n    on component bootstrap we decide what we want to do. When we remove display none it performs the browser native behavior.\n\n### :floppy_disk: Caching\n\nWe use a DOM caching mechanism to display svg over the 'use' tag and an href attribute.\nWhen the browser loaded the svg resource we trigger the caching mechanism.\n\n`re-fetch -\u003e cache-hit -\u003e get SVG -\u003e cache in DOM`\n\nCached SVG elements can be reused in multiple places and support different styling.\n\n### :rocket: Optimized for performance\n\nThis library leverages best performance practices:\n\n- Component is styled with `content-visiblity: auto;` and `contain: content;`. It makes instances outside of viewport completely excluded from browser style recalculation process.\n- Cache is stored in a tag which is not processed by the browser.\n- We use native browser `fetch` which is not patched by `zone.js` and is on average 2.5 times faster than fetching over `HTTPClient`.\n\n### 🤖 SSR Support\n\nThis library also supports SSR. url and loading function can be configured over DI.\n\n\n### 🤖 SSR Transfere State (rendered SVG as HTML)\n\nIf SSR load svgs on server the rendered HTML ends up in DOM cache and ships to the client.\nOn the client no additional requests are needed.\n\n## Comparison\n\n\u003e 🖥️ Interactive demo available [here](https://push-based.github.io/ngx-fast-svg).\n\nHere's library comparison with other popular SVG solutions.\n\n| Library          | SSR [1]    | Lazy loading [2]  | Optimized render performance [3] | Transfere State | Size     |\n|------------------|------------|-------------------|----------------------------------|-----------------|----------|\n| ngx-fast-svg     | `easy`     | browser natively  | ✔️                                | ✔️               | 1.52 KB  |\n| ionic            | `moderate` | viewport observer | ✔️                               | ❌               | 1.44 KB  |\n| angular-svg-icon | `moderate` | ❌                | ❌                               | ❌               | 1.54 KB  |\n| material         | `easy`     | ❌                | ❌                               | ❌               | 16.92 KB |\n| ant              | `moderate` | ❌                | ❌                               | ❌               | 24.38 KB |\n| font-awesome     | `hard`     | ❌                | ❌                               | ❌               | 64.75 KB |\n\n**[1] SSR**\nServer Side Rendering is working. The depending on how easy it is to set it up we distinguish between `easy`, `moderate`, `hard`.\n\n**[2] Lazy loading**\nWe refer to lazy loading as on demand loading of SVG files based on their visibility in the viewport.\n\n\u003c!-- **Hydration**\nIs the process of taking over the SSR HTML and state of the app on the client side.\nThis can happen in a destructive way (deleting all present HTML and regenerate it from JS) on in a non-destructive way (reusing the existing DOM).\n\n** Reusability of SVG DOM**\nReusability means that we maintain the content of an SVG, meaning its inner DOM structure `g`, `path` or other tags in one place and reuse them in many different places. --\u003e\n\n**[3] Optimized render performance**\nTo display (render) SVGs the browser takes time. We can reduce that time by adding a couple of improvements.\n\n---\n\nmade with ❤ by [push-based.io](https://www.push-based.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpush-based%2Fngx-fast-svg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpush-based%2Fngx-fast-svg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpush-based%2Fngx-fast-svg/lists"}