Phosphor Icons for Vue

Common errors

• [Vue warn]: Unknown custom element: <ph-icon-name> - did you register the component correctly?

  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)`.
  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);`.

• 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;
  }'

  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.
  fix Ensure 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

  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.
  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`.

Warnings

• breaking 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`.
  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`.
• gotcha 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.
  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);`
• gotcha 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.
  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.
• deprecated 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'.
  Fix: Opt for individual icon imports and local or explicit global registration to leverage tree-shaking benefits and optimize bundle size.

Install

• npm install phosphor-vue npm
• yarn add phosphor-vue yarn
• pnpm add phosphor-vue pnpm

Imports

• PhosphorVue
  wrong:

  const PhosphorVue = require('phosphor-vue')

  correct:

  import PhosphorVue from 'phosphor-vue'

  Default export primarily for global plugin registration in Vue 3 applications. CommonJS `require` is not supported in v2.x.
• PhHorse, PhHeart
  wrong:

  import PhosphorVue from 'phosphor-vue/icons/PhHorse'

  correct:

  import { PhHorse, PhHeart } from 'phosphor-vue'

  Individual icons are named exports. Each icon component is prefixed with 'Ph'. Importing specific icons enables tree-shaking.
• IconProps, IconWeight
  wrong:

  import { IconProps } from 'phosphor-vue'

  correct:

  import type { IconProps, IconWeight } 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`.

Quickstart

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>
*/