Vue 3 Icon Component

3.0.3 · active · verified Sun Apr 19

Vue3 Icon is a dedicated Vue 3 component designed for effortlessly rendering SVG path-based icons within modern Vue applications. Currently stable at version 3.0.3, the library receives updates to maintain compatibility with the latest Vue releases and address evolving development practices. Its release cadence is moderate, typically involving major version bumps for significant architectural changes or new features, such as the shift to an ESM-first architecture in v3.0.0 and the adoption of Vite for its build process in v2.0.0. A key differentiator is its versatility, supporting icon data from popular libraries like Material Design Icons (`@mdi/js`), various Font Awesome packages, Simple Icons, and even custom SVG paths. It offers flexible props for controlling icon size, color, rotation, and custom viewbox settings, providing developers with granular control over icon presentation without bundling entire icon font libraries.

Common errors

```
Module not found: Can't resolve 'vue3-icon'
```
cause Attempting to `require('vue3-icon')` in a CommonJS environment after v3.0.0, or module resolver misconfiguration.

fix Switch to `import SvgIcon from 'vue3-icon'` and ensure your project's build setup supports ESM. For Node.js, ensure `"type": "module"` is set in `package.json` or use an appropriate transpiler.
```
ReferenceError: SvgIcon is not defined
```
cause The `SvgIcon` component was not imported or registered globally/locally in the Vue application.

fix Import `SvgIcon` from 'vue3-icon' (e.g., `import SvgIcon from 'vue3-icon';`) and either register it globally (`app.component('svg-icon', SvgIcon)`) or locally within your component's `components` option.
```
Cannot read properties of undefined (reading 'path')
```
cause A FontAwesome icon object (which contains an SVG path and other metadata) was passed to the `path` prop instead of the `fa-icon` prop.

fix If using a FontAwesome icon, use the `:fa-icon` prop: `<svg-icon :fa-icon="faCoffee"></svg-icon>`. The `path` prop expects a simple SVG path string.

Warnings

breaking Version 3.0.0 shifted the package to an ESM-first architecture. Projects using CommonJS `require()` might encounter module resolution errors.
Fix: Migrate your project to use ESM `import` statements. Ensure your build configuration (e.g., Vite, webpack) is set up for ESM resolution.
breaking Version 2.0.0 changed the library's build system to Vite. Direct imports to specific files within the `dist` directory might require updating file paths.
Fix: Review your `import` statements if you were directly referencing files like `dist/vue3-icon.cjs.js`. Prefer the main entry point `vue3-icon` to let module resolvers handle the correct file.
gotcha The `vue3-icon` component only provides the rendering logic, not the icon data itself. Users must install separate icon packages (e.g., `@mdi/js`, `@fortawesome/free-solid-svg-icons`, `simple-icons`) to obtain icon paths or objects.
Fix: Install the required icon package (e.g., `npm install @mdi/js`) and import the specific icon data from that package as shown in the examples.
gotcha FontAwesome icons require the `fa-icon` prop, while other SVG paths use the `path` prop. Using the wrong prop will result in the icon not rendering correctly or throwing an error.
Fix: When using FontAwesome icon objects (e.g., `faCoffee`), pass them to the `:fa-icon` prop. For simple SVG path strings, use the `:path` prop.

Install

npm install vue3-icon npm
yarn add vue3-icon yarn
pnpm add vue3-icon pnpm

Imports

SvgIcon
wrong:
```
const SvgIcon = require('vue3-icon')
```
correct:
```
import SvgIcon from 'vue3-icon'
```
The package became ESM-first in v3.0.0; CommonJS `require` is no longer the primary method.
mdiAccount
```
import { mdiAccount } from '@mdi/js'
```
Icon paths like `mdiAccount` are typically named exports from their respective icon packages. `@mdi/js` must be installed separately.
faCoffee
```
import { faCoffee } from '@fortawesome/free-solid-svg-icons'
```
FontAwesome icon objects are named exports. The specific FontAwesome package (e.g., `@fortawesome/free-solid-svg-icons`) must be installed separately.

Quickstart

This quickstart demonstrates how to globally register the `SvgIcon` component, import an icon path from Material Design Icons, and define a custom SVG path. It then renders both icons with basic styling in a Vue 3 application.

import { createApp } from 'vue';
import SvgIcon from 'vue3-icon';
import { mdiAccount } from '@mdi/js';

const app = createApp({
  setup() {
    const myCustomIcon = "M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z";
    return {
      mdiAccount,
      myCustomIcon
    };
  },
  template: `
    <div id="app">
      <h1>Vue3 Icon Example</h1>
      <p>Material Design Icon:</p>
      <svg-icon type="mdi" :path="mdiAccount" :size="48" style="color: dodgerblue;"></svg-icon>
      <p>Custom SVG Path Icon (with custom viewbox and color):</p>
      <svg-icon :path="myCustomIcon" size="24" viewbox="0 0 24 24" style="color: green;"></svg-icon>
    </div>
  `,
});

app.component("svg-icon", SvgIcon);
app.mount("#app");

view raw JSON →