Vue

Icon Forge gives you Vue single-file components — one .vue file per icon, with inline SVG and attribute fallthrough. No runtime dependency, no icon font. Just local source files you import like your own code.

Install a pack

From your project root:

npx @icon-forge/cli install acme/brand/core-icons --framework vue

The CLI downloads the published pack and writes it into your project:

src/components/icons/core-icons/
├── ArrowLeft.vue
├── CheckCircle.vue
├── Home.vue
├── Settings.vue
├── ...
└── index.ts

On the first install, the CLI creates two tracking files at the project root:

iconforge.json — your install config (framework, output directory, which packs you’re tracking)
iconforge-lock.json — exact record of what’s installed (versions, file hashes)

Commit both, along with the component directory.

Your framework choice is saved after the first install — the CLI won’t ask again.

Importing icons

Each pack gets a barrel index.ts, so named imports work out of the box:

import { ArrowLeft, CheckCircle, Home } from "@/components/icons/core-icons";

Or import individual files directly:

import ArrowLeft from "@/components/icons/core-icons/ArrowLeft.vue";

Using icons in templates

Icons are standard Vue components. They render an inline <svg> as the root node, and Vue’s attribute fallthrough passes your classes, styles, and attributes straight through.

<script setup lang="ts">
import { ArrowLeft, CheckCircle } from "@/components/icons/core-icons";
</script>

<template>
  <div class="flex items-center gap-2">
    <ArrowLeft class="h-5 w-5" />
    <CheckCircle class="h-5 w-5 text-emerald-600" />
  </div>
</template>

Sizing and color

Default color is currentColor — icons inherit your text color
Default size is 1em
Pass class, style, width, height, or any SVG attribute to customize

The standard Tailwind / utility-class pattern works as you’d expect:

<Home class="h-6 w-6 text-muted-foreground" />

Event handlers

Vue’s event binding works directly on icon components:

<ArrowLeft class="h-5 w-5 cursor-pointer" @click="handleBack" />

Dynamic classes and bindings

All standard Vue bindings work since these are regular components:

<CheckCircle
  :class="[
    'h-5 w-5 transition-colors',
    isValid ? 'text-green-600' : 'text-gray-400'
  ]"
/>

Accessibility

Icons are presentational by default. If an icon carries meaning (not just decoration), add a label at the call site:

<CheckCircle aria-label="Success" class="h-5 w-5 text-green-600" />

For decorative icons next to text, no extra attributes are needed — screen readers will skip the SVG.

Wrapping icons

The installed component files are managed by the CLI — they get replaced on the next install or update. If you need app-specific behavior (animation, tooltips, semantic wrappers), build a wrapper component in your own code:

<script setup lang="ts">
import { CheckCircle, XCircle, Clock } from "@/components/icons/core-icons";

const props = defineProps<{
  status: "success" | "error" | "pending";
}>();

const iconMap = {
  success: CheckCircle,
  error: XCircle,
  pending: Clock,
} as const;
</script>

<template>
  <component :is="iconMap[props.status]" v-bind="$attrs" />
</template>

Don’t edit the generated files directly — your changes will be overwritten.

Nuxt

Icon Forge components work in Nuxt projects the same way. Install with --framework vue and import as usual. Since the icons are local .vue files, Nuxt’s auto-import can pick them up if your output directory is inside a components folder — or you can import them explicitly.

Updating

When the design team publishes a new version of the pack:

npx @icon-forge/cli install acme/brand/core-icons

The CLI pulls the latest release and replaces the tracked files. Component names (based on slot names) stay stable across updates unless the pack author renamed a slot.

To lock to a specific release:

npx @icon-forge/cli install acme/brand/core-icons --version 8f3a9c2d14be

See Updating & Pinning for more on version management.

Multiple packs

You can install multiple packs into the same Vue project. Each gets its own folder:

src/components/icons/
├── core-icons/
│   ├── Home.vue
│   └── index.ts
└── nav-icons/
    ├── ChevronLeft.vue
    └── index.ts

Import from each barrel separately:

import { Home } from "@/components/icons/core-icons";
import { ChevronLeft } from "@/components/icons/nav-icons";

Output customization

Change where packs are written:

# Different base directory
npx @icon-forge/cli install acme/brand/core-icons --output-dir src/icons

# Different folder name for this pack
npx @icon-forge/cli install acme/brand/core-icons --dir-name core

These settings are saved in iconforge.json after the first install.

Next steps

Config & Lockfile

How iconforge.json and iconforge-lock.json work.

The Workspace

How icon packs are built on the curate side.

Publishing

How releases and namespaces work.