Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PhosphorVue
✓ import PhosphorVue from 'phosphor-vue'
✗ const PhosphorVue = require('phosphor-vue')
Default export primarily for global plugin registration in Vue 3 applications. CommonJS `require` is not supported in v2.x.
PhHorse, PhHeart
✓ import { PhHorse, PhHeart } from 'phosphor-vue'
✗ import PhosphorVue from 'phosphor-vue/icons/PhHorse'
Individual icons are named exports. Each icon component is prefixed with 'Ph'. Importing specific icons enables tree-shaking.
IconProps, IconWeight
✓ import type { IconProps, IconWeight } from 'phosphor-vue'
✗ import { IconProps } from 'phosphor-vue'
Type imports for TypeScript users to get prop definitions for icon components, ensuring type safety when using custom props like `size`, `color`, and `weight`.
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.
import { createApp } from 'vue';
import PhosphorVue from 'phosphor-vue';
import App from './App.vue';
const app = createApp(App);
// Register PhosphorVue as a global plugin
app.use(PhosphorVue);
app.mount('#app');
// App.vue example
/*
<template>
<div>
<h1>My App</h1>
<ph-heart :size="32" color="red" weight="fill" />
<ph-cube :size="24" color="blue" />
<ph-star :weight="isStarred ? 'fill' : 'regular'" @click="toggleStar" />
</div>
</template>
<script setup>
import { ref } from 'vue';
const isStarred = ref(false);
const toggleStar = () => { isStarred.value = !isStarred.value; };
</script>
*/
Debug
Known issues
breakingVersion 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`.fixFor 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`.
affects: >=2.0.0-alpha.1
gotchaWhile 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.fixPrefer 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);` affects: >=1.0.0
gotchaTree-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.fixEnsure 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.
affects: >=2.0.0-alpha.1 <2.0.3
deprecatedThe 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'.fixOpt for individual icon imports and local or explicit global registration to leverage tree-shaking benefits and optimize bundle size.
affects: >=2.1.4
Errors
Common errors & fixes
[Vue warn]: Unknown custom element: <ph-icon-name> - did you register the component correctly?
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)`.
fixEither 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);`. Property 'weight' does not exist on type 'IntrinsicAttributes & SVGAttributes<SVGElement> & {
color?: string | undefined;
size?: string | number | undefined;
weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" | undefined;
}'
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.
fixEnsure the `weight` prop value is one of the explicitly defined types: `'thin'`, `'light'`, `'regular'`, `'bold'`, `'fill'`, or `'duotone'`.
Error: Cannot find module 'phosphor-vue' or Error: require() of ES Module ... not supported
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.
fixEnsure 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`.
Audit
Dependencies
vuerequiredPeer dependency, required for Vue integration. Version ^3.2.39 for v2.x of phosphor-vue, ^2.6.11 for v1.x.