Iconsax Icon Pack for Vue

Common errors

• Failed to resolve component: VsxIcon

  cause The `VsxIcon` component has not been correctly registered within your Vue application, either globally or locally.
  fix Globally register the component in your `main.js` file using `app.component('VsxIcon', VsxIcon)` or import and declare it in the `components` option of your specific Vue component.

• Icon not displaying, or showing as a blank space/broken image.

  cause This usually indicates an incorrect `iconName` prop value (e.g., misspelled, wrong casing) or an invalid `type` prop.
  fix Double-check that the `iconName` prop exactly matches an existing Iconsax icon in PascalCase and that the `type` prop (e.g., 'linear', 'bold', 'broken') is one of the six supported values and correctly spelled.

• Uncaught SyntaxError: Cannot use import statement outside a module

  cause This error occurs when trying to use ES module `import` syntax in a CommonJS environment (e.g., older Node.js versions or misconfigured bundlers). `vue-iconsax` is an ESM-only package.
  fix Ensure your project is configured for ES Modules. If using Node.js, add `"type": "module"` to your `package.json` or use `.mjs` file extensions. For bundlers like Webpack or Vite, ensure they are configured to handle ES Modules correctly.

Warnings

• breaking vue-iconsax v2.0.0 and subsequent versions are exclusively designed for Vue 3 and are not compatible with Vue 2 applications. Attempting to use it in a Vue 2 project will result in runtime errors.
  Fix: Ensure your project is running Vue 3.x. If using Vue 2, you must either upgrade your Vue project or find an alternative icon library compatible with Vue 2.
• gotcha The `iconName` prop for the `VsxIcon` component strictly requires icon names to be provided in PascalCase (e.g., 'Add', 'Home', 'UserSearch'). Using kebab-case, snake_case, or any other casing will result in the icon not rendering.
  Fix: Always refer to the official Iconsax documentation or browse the available icons to ensure the exact PascalCase name is used for the `iconName` prop.
• gotcha This library does not support individual icon component imports (e.g., `import { AddIcon } from 'vue-iconsax'`). All icons are dynamically loaded and rendered solely through the generic `VsxIcon` component by specifying the icon's name via the `iconName` prop.
  Fix: Always use the `VsxIcon` component and pass the desired icon name as a string to the `iconName` prop.

Install

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

Imports

• VsxIcon
  wrong:

  const VsxIcon = require('vue-iconsax')

  correct:

  import { VsxIcon } from 'vue-iconsax'

  The primary and typically only component for rendering all Iconsax icons dynamically via props. This library is ESM-only since v2.0.0 and explicitly requires Vue 3. Using CommonJS `require` will lead to errors.
• VsxIcon (for global registration)
  wrong:

  import VsxIcon from 'vue-iconsax'

  correct:

  import { VsxIcon } from 'vue-iconsax'

  When registering globally with `app.component('VsxIcon', VsxIcon)`, ensure it's a named import. Attempting a default import will fail as `vue-iconsax` exports `VsxIcon` as a named export.
• VsxIcon (for local registration)
  wrong:

  import { Vsxicon } from 'vue-iconsax'

  correct:

  import { VsxIcon } from 'vue-iconsax'

  When importing for local component registration, ensure `VsxIcon` is spelled with correct PascalCase. JavaScript is case-sensitive, and a mismatch will prevent the component from being resolved.

Quickstart

This example demonstrates how to globally register the `VsxIcon` component in `main.js` and then dynamically change the displayed icon in an `App.vue` component using Vue 3's Composition API.

import { createApp, ref } from 'vue';
import App from './App.vue';
import { VsxIcon } from 'vue-iconsax';

// main.js - Global registration of VsxIcon component
const app = createApp(App);
app.component('VsxIcon', VsxIcon);
app.mount('#app');

// App.vue - Example usage in a Vue component
export default {
  name: 'App',
  setup() {
    const iconNames = ['Activity', 'Archive1', 'Bookmark', 'Chart', 'Cloud'];
    let currentIndex = ref(0);
    const currentIcon = ref(iconNames[currentIndex.value]);

    const cycleIcon = () => {
      currentIndex.value = (currentIndex.value + 1) % iconNames.length;
      currentIcon.value = iconNames[currentIndex.value];
    };

    return {
      currentIcon,
      cycleIcon
    };
  },
  template: `
    <div id="app" style="font-family: Avenir, Helvetica, Arial, sans-serif; text-align: center; color: #2c3e50; margin-top: 60px; display: flex; flex-direction: column; align-items: center; gap: 20px;">
      <h1>Dynamic Iconsax Demo</h1>
      <VsxIcon :iconName="currentIcon" color="#4a90e2" size="64" type="twotone" />
      <p>Current Icon: <strong>{{ currentIcon }}</strong></p>
      <button @click="cycleIcon" style="padding: 10px 20px; font-size: 1em; cursor: pointer; border: 1px solid #4a90e2; background-color: #4a90e2; color: white; border-radius: 5px;">Next Icon</button>
    </div>
  `
};