{"id":14810,"library":"phosphor-vue","title":"Phosphor Icons for Vue","description":"Phosphor-vue provides a comprehensive set of highly customizable SVG icons specifically tailored for Vue.js applications. The library is currently stable at version `2.2.0` for Vue 3 projects, offering a wide range of icons with multiple display weights (thin, light, regular, bold, fill, duotone). For Vue 2 users, version `1.x` branches are maintained separately. Releases typically align with updates to the core Phosphor Icons library, introducing new icons and bug fixes. Key differentiators include robust TypeScript support, a focus on flexibility through various icon weights for dynamic styling and state representation, and support for both global and individual component registration to balance convenience with bundle size optimization. It integrates seamlessly into Vue's component system, accepting standard SVG attributes and custom props for styling.","status":"active","version":"1.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/phosphor-icons/phosphor-vue","tags":["javascript","vue","icons","svg","phosphor","design","interface","UI","UX","typescript"],"install":[{"cmd":"npm install phosphor-vue","lang":"bash","label":"npm"},{"cmd":"yarn add phosphor-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add phosphor-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for Vue integration. Version ^3.2.39 for v2.x of phosphor-vue, ^2.6.11 for v1.x.","package":"vue","optional":false}],"imports":[{"note":"Default export primarily for global plugin registration in Vue 3 applications. CommonJS `require` is not supported in v2.x.","wrong":"const PhosphorVue = require('phosphor-vue')","symbol":"PhosphorVue","correct":"import PhosphorVue from 'phosphor-vue'"},{"note":"Individual icons are named exports. Each icon component is prefixed with 'Ph'. Importing specific icons enables tree-shaking.","wrong":"import PhosphorVue from 'phosphor-vue/icons/PhHorse'","symbol":"PhHorse, PhHeart","correct":"import { PhHorse, PhHeart } from 'phosphor-vue'"},{"note":"Type imports for TypeScript users to get prop definitions for icon components, ensuring type safety when using custom props like `size`, `color`, and `weight`.","wrong":"import { IconProps } from 'phosphor-vue'","symbol":"IconProps, IconWeight","correct":"import type { IconProps, IconWeight } from 'phosphor-vue'"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport PhosphorVue from 'phosphor-vue';\nimport App from './App.vue';\n\nconst app = createApp(App);\n\n// Register PhosphorVue as a global plugin\napp.use(PhosphorVue);\n\napp.mount('#app');\n\n// App.vue example\n/*\n<template>\n  <div>\n    <h1>My App</h1>\n    <ph-heart :size=\"32\" color=\"red\" weight=\"fill\" />\n    <ph-cube :size=\"24\" color=\"blue\" />\n    <ph-star :weight=\"isStarred ? 'fill' : 'regular'\" @click=\"toggleStar\" />\n  </div>\n</template>\n\n<script setup>\nimport { ref } from 'vue';\nconst isStarred = ref(false);\nconst toggleStar = () => { isStarred.value = !isStarred.value; };\n</script>\n*/","lang":"typescript","description":"Demonstrates global installation of PhosphorVue as a plugin for a Vue 3 application, allowing any icon to be used directly in templates without individual imports."},"warnings":[{"fix":"For Vue 2 projects, install `phosphor-vue@1` or consult the `vue2` branch on GitHub. For Vue 3 projects, ensure your Vue version meets the peer dependency `^3.2.39`.","message":"Version 2.0.0 introduced breaking changes by dropping support for Vue 2.x. Projects using Vue 2 must remain on the 1.x branch of `phosphor-vue`.","severity":"breaking","affected_versions":">=2.0.0-alpha.1"},{"fix":"Prefer importing and registering individual icons you intend to use. This allows bundlers to effectively remove unused icons from your final build. Example: `import { PhHorse } from 'phosphor-vue'; app.component('PhHorse', PhHorse);`","message":"While a global plugin installation method exists, it is strongly advised against for production applications as it can significantly increase bundle size and prevent effective tree-shaking.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you are on `phosphor-vue@2.0.3` or newer, which updated peer dependencies and improved tree-shakability. For older versions, explicitly import only the icons you need, and verify your bundler configuration.","message":"Tree-shaking for `phosphor-vue` (especially in early v2.x versions) could be problematic, causing build systems to hang or generate excessively large bundles. This was particularly noted with Nuxt 3 and certain Vue 3 configurations.","severity":"gotcha","affected_versions":">=2.0.0-alpha.1 <2.0.3"},{"fix":"Opt for individual icon imports and local or explicit global registration to leverage tree-shaking benefits and optimize bundle size.","message":"The ability to globally install icons utilizing the default export was added in v2.1.4, but the maintainers still 'strongly advise against global installs, since they break tree-shaking'.","severity":"deprecated","affected_versions":">=2.1.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Either register `PhosphorVue` as a global plugin (`app.use(PhosphorVue)`) or explicitly import and register each icon component you use, e.g., `import { PhHorse } from 'phosphor-vue'; app.component('PhHorse', PhHorse);`.","cause":"The icon component (e.g., `<ph-horse>`) was used in a template but not imported and registered globally via `app.use(PhosphorVue)` or locally/globally via `app.component('PhHorse', PhHorse)`.","error":"[Vue warn]: Unknown custom element: <ph-icon-name> - did you register the component correctly?"},{"fix":"Ensure the `weight` prop value is one of the explicitly defined types: `'thin'`, `'light'`, `'regular'`, `'bold'`, `'fill'`, or `'duotone'`.","cause":"A type mismatch or incorrect value passed to the `weight` prop. This usually happens if a string outside the allowed literal union types (\"thin\", \"light\", etc.) is provided.","error":"Property 'weight' does not exist on type 'IntrinsicAttributes & SVGAttributes<SVGElement> & {\n    color?: string | undefined;\n    size?: string | number | undefined;\n    weight?: \"thin\" | \"light\" | \"regular\" | \"bold\" | \"fill\" | \"duotone\" | undefined;\n}'"},{"fix":"Ensure your project uses ES Modules (`import ... from 'phosphor-vue'`) and a compatible bundler. If targeting older Node.js or CommonJS, consider transpilation or using the Vue 2 compatible `phosphor-vue@1`.","cause":"Attempting to use `require()` for `phosphor-vue` v2.x in a CommonJS environment, or a bundling issue where the module resolution fails for the ESM-only package.","error":"Error: Cannot find module 'phosphor-vue' or Error: require() of ES Module ... not supported"}],"ecosystem":"npm"}