{"id":25672928,"url":"https://github.com/jevon617/unplugin-svg-component","last_synced_at":"2025-08-13T19:48:55.687Z","repository":{"id":61678860,"uuid":"548796878","full_name":"Jevon617/unplugin-svg-component","owner":"Jevon617","description":"generate a vue/react component through svg files, supporting svg file HMR, Tree-shaking, SSR and TS hint.","archived":false,"fork":false,"pushed_at":"2024-05-22T02:45:13.000Z","size":911,"stargazers_count":42,"open_issues_count":4,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-22T12:10:14.661Z","etag":null,"topics":["icons","react","svg","svg-sprites","typescript","vue"],"latest_commit_sha":null,"homepage":"","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/Jevon617.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":"2022-10-10T07:39:50.000Z","updated_at":"2024-05-28T12:15:07.408Z","dependencies_parsed_at":"2024-01-05T07:33:25.389Z","dependency_job_id":"8f8e3728-5eac-45fd-8cb9-0e711f0ab8ca","html_url":"https://github.com/Jevon617/unplugin-svg-component","commit_stats":{"total_commits":65,"total_committers":1,"mean_commits":65.0,"dds":0.0,"last_synced_commit":"797cb1df74e2682c809bc2cd10b9999fd2ae210d"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":"unplugin/unplugin-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jevon617%2Funplugin-svg-component","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jevon617%2Funplugin-svg-component/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jevon617%2Funplugin-svg-component/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jevon617%2Funplugin-svg-component/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jevon617","download_url":"https://codeload.github.com/Jevon617/unplugin-svg-component/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250367420,"owners_count":21418887,"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":["icons","react","svg","svg-sprites","typescript","vue"],"created_at":"2025-02-24T12:19:57.722Z","updated_at":"2025-04-23T04:22:28.151Z","avatar_url":"https://github.com/Jevon617.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# unplugin-svg-component\n\n**English** | [中文](./README.zh_CN.md)\n\n[![NPM Version][npm-image]][npm-url]\n[![Downloads Stats][npm-downloads]][npm-url]\n\n\u003e unplugin-svg-component inspired by [vite-plugin-svg-icons](https://github.com/vbenjs/vite-plugin-svg-icons), it will generate a Vue/React component through SVG files,  use the SVG icon through the component.\n\n## IDE Intelligent\n\n### Vue\n![image](./images/intellisense.jpg)\n\n### React\n![image](./images/intellisense-react.jpg)\n\n## Features\n\n* **intelligent**: When using components, the name of the SVG file will be prompted with Typescript\n* **HMR**: HMR for svg file\n* **Vue \u0026 React**: Support Vue\u0026React and automatically detect project types.\n* **Tree-shaking**: Only bundle the icons you really use since **v0.5.0**.\n* **SSR**: Support SSR by enabling the `option.domInsertionStrategy = replaceHtml`(default) since **v0.6.0**.\n\n## Installation\n\n```shell\nyarn add unplugin-svg-component -D\n# or\nnpm i unplugin-svg-component -D\n# or\npnpm install unplugin-svg-component -D\n```\n\n## Usage\n\n\u003cdetails\u003e\n\u003csummary\u003eVite config\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// vite.config.ts\nimport { defineConfig } from 'vite'\nimport UnpluginSvgComponent from 'unplugin-svg-component/vite'\n\nexport default defineConfig({\n  plugins: [\n    UnpluginSvgComponent({ /* options */ }),\n  ],\n})\n```\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eVue-cli config\u003c/summary\u003e\u003cbr\u003e\n\n```js\n// vue.config.js\nconst { defineConfig } = require('@vue/cli-service')\nconst UnpluginSvgComponent = require('unplugin-svg-component/webpack').default\n\nmodule.exports = defineConfig({\n  configureWebpack: {\n    plugins: [\n      UnpluginSvgComponent({ /* options */ })\n    ]\n  }\n})\n```\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWebpack config\u003c/summary\u003e\u003cbr\u003e\n\n```js\n// webpack.config.js\nconst UnpluginSvgComponent = require('unplugin-svg-component/webpack').default\n\nmodule.exports = {\n  /* ... */\n  plugins: [\n    UnpluginSvgComponent({ /* options */ }),\n  ],\n}\n```\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRollup config\u003c/summary\u003e\u003cbr\u003e\n\n```js\n// rollup.config.js\nimport UnpluginSvgComponent from 'unplugin-svg-component/rollup'\n\nexport default {\n  plugins: [\n    UnpluginSvgComponent({ /* options */ }),\n  ],\n}\n```\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eEsbuild config\u003c/summary\u003e\u003cbr\u003e\n\n```js\n// esbuild.config.js\nimport { build } from 'esbuild'\nimport UnpluginSvgComponent from 'unplugin-svg-component/esbuild'\n\nbuild({\n  /* ... */\n  plugins: [\n    UnpluginSvgComponent({\n      /* options */\n    }),\n  ],\n})\n```\n\u003cbr\u003e\u003c/details\u003e\n\n### Vue\n```ts\n// main.ts\nimport SvgIcon from '~virtual/svg-component'\n\napp.component(SvgIcon.name, SvgIcon)\n```\n\n### React\n```tsx\n// App.tsx\nimport SvgIcon from '~virtual/svg-component'\n\nfunction App() {\n  return (\n    \u003cdiv className=\"logo\"\u003e\n      \u003cSvgIcon name=\"icon-react\"\u003e\u003c/SvgIcon\u003e\n    \u003c/div\u003e\n  )\n}\n```\n\n### Get `svgNames` / type `SvgName`\n\n```ts\n// all svg icon name\nimport { svgNames } from '~virtual/svg-component'\n\n// type SvgName = \"icon-icon-addUser\" | \"icon-icon-barCode\"\nimport type { SvgName } from '~virtual/svg-component'\n```\n\n## Plugin Configuration\n\n| Parameter             | Type                       | Default                                        | Description                                         |\n| -----------           | ----------------------     | ---------------------                          | ------------                                        |\n| iconDir               | `string \\| string[]`     | -                                              | the icon folder of the Sprite image                 |\n| projectType           | `vue \\| react \\| auto`     | auto                                           | the project type, detect automatically              |\n| dts                   | `boolean`                  | -                                              | whether generate d.ts file                          |\n| dtsDir                | `string`                   | -                                              | d.ts location                                       |\n| prefix                | `string`                   | -                                              | symbolId prefix                                     |\n| componentName         | `string`                   | SvgIcon                                        | the name of component                               |\n| componentStyle        | `string`                   | width: 1em; height: 1em; fill:currentColor;    | the style of component                              |\n| preserveColor         |`RegExp`                    | -                                              | usually, the plugin will set SVG's fill and stroke with 'currentColor', this option will perform regular matching on each SVG path, the successfully matched SVG will not do the replacement, but retain the original color.  |\n| symbolIdFormatter     | `(svgName:string, prefix: string)=\u003estring` | [look this way](./src/core/utils.ts/#L33)               | the symbolId's formatter            |\n| optimizeOptions       | `SvgoOptions` | -          | svgo optimize [Options](https://github.com/svg/svgo) |\n| svgSpriteDomId        | `string`                   | __svg_sprite__dom__                            | Customize the ID of the svgDom                      |\n| vueVersion            | `2 \\| 3 \\| auto`           | auto                                           | Vue version                                         |\n| treeShaking           | `boolean`                  | true                                          | whether enable tree-shaking                         |\n| scanGlob            | `string[]`           | [look this way](./src/core/utils.ts/#L41)                        |  the glob pattern used in tree-shaking                                          |\n| scanStrategy            | `text \\| component \\| (code: string[], options: Options)=\u003estring[]`       | component                        |  the strategy used for tree-shaking will not be bundled into the final bundle if it is not successfully matched. The `text` option indicates matching by svg name, so you should ensure the uniqueness of your svg name (you can consider customizing it with the 'symbolIdFormatter' option) to avoid erroneous tree-shaking, while the default value of the `component` option indicates matching by component as a whole, In addition, you can also implement a tree-shaking strategy by passing a function whose return value represents the set of SVG icons used.                                          |\n| domInsertionStrategy            | `replaceHtml \\| dynamic`        | `replaceHtml`                        |  controls the method of injecting SVG elements, `replaceHtml(default)`: Injects the SVG elements by replacing the HTML string in server. `dynamic`: Injects the SVG elements through JavaScript dynamically in client. **Warning: if you are in ssr mode, you should use `replaceHtml` strategy.**|\n\n## Typescript support\n```json\n// tsconfig.json\n{\n  \"include\": [\"svg-component.d.ts\", \"svg-component-global.d.ts\"]\n}\n```\n\n## Best Practices\n\nYou can refer to [examples](./examples) as required. Note that the configuration in examples is the default configuration.\n\n## Contributing\n\n1. Fork it (\u003chttps://github.com/Jevon617/unplugin-svg-component/fork\u003e)\n2. Create your feature branch (`git checkout -b feature/fooBar`)\n3. Commit your changes (`git commit -am 'Add some fooBar'`)\n4. Push to the branch (`git push origin feature/fooBar`)\n5. Create a new Pull Request\n\n## License\nMIT License © 2022-PRESENT [Jevon617](https://github.com/Jevon617)\n\n\u003c!-- Markdown link \u0026 img dfn's --\u003e\n[npm-image]: https://img.shields.io/npm/v/unplugin-svg-component.svg?style=flat-square\n[npm-url]: https://npmjs.org/package/unplugin-svg-component\n[npm-downloads]: https://img.shields.io/npm/dm/unplugin-svg-component.svg?style=flat-square\n[travis-image]: https://img.shields.io/travis/dbader/node-datadog-metrics/master.svg?style=flat-square\n[travis-url]: https://travis-ci.org/dbader/node-datadog-metrics\n[wiki]: https://github.com/yourname/yourproject/wiki\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjevon617%2Funplugin-svg-component","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjevon617%2Funplugin-svg-component","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjevon617%2Funplugin-svg-component/lists"}