sv-iconify

Iconify icons for Svelte

Access all Iconify icons in your SvelteKit project. Uses static code analysis to detect icon usage and bundles only the icons you need, enabling offline access and minimal bundle sizes.

Limitations

• Emojis iconsets is not available due to their large size.

Installation

npm install sv-iconify -D
# or
pnpm add sv-iconify -D

Setup

Add the Vite plugin to your vite.config.ts:

import { defineConfig } from "vite";
import { sveltekit } from "@sveltejs/kit/vite";
import { svIconify } from "sv-iconify/vite";

export default defineConfig({
    plugins: [
        svIconify(), // Required - scans your code and bundles icons
        sveltekit(),
    ],
});

The plugin is required for icons to work. It scans your code for icon usage and creates a bundle containing only the icons you use.

see below section for configuration options.

Basic Usage

Import and use the Icon component in your Svelte files:

<script>
import { Icon } from "sv-iconify";
</script>

<Icon icon="mdi:home" />
<Icon icon="carbon:user-avatar" width={32} />
<Icon icon="lucide:settings" color="blue" />

Icon Props

Examples

<!-- Basic usage -->
<Icon icon="mdi:home" />

<!-- Custom size -->
<Icon icon="carbon:user" width="{24}" />
<Icon icon="carbon:user" width="1rem" />
<Icon icon="carbon:user" width="24" />

<!-- Custom color -->
<Icon icon="lucide:heart" color="red" />
<Icon icon="lucide:heart" color="var(--red-600)" />

<!-- Rotation -->
<Icon icon="mdi:arrow-right" rotate="90deg" />

<!-- Flip -->
<Icon icon="mdi:arrow-left" hFlip />
<Icon icon="mdi:arrow-left" vFlip />

How It Works

The plugin uses static code analysis to scan your source code for icon usage (e.g., icon="mdi:home") and creates an optimized bundle:

• Development mode: All icons are available and served on demand from the library
• Production mode: Only the icons detected in your code are bundled, optimized for size and offline access

If an icon can't be found in the bundle, it falls back to the Iconify API and fetches the icon over the network.

Configuration

The Vite plugin can be configured with the following options:

• sourceDir (string)

  • Path to the directory containing icon JSON files.
  • Default: Auto-detect from node_modules - node_modules/sv-iconify/dist/data/json

• outputPath (string)

  • Output path for the generated icon bundle (production builds only).
  • Default: 'static/_sv-iconify/icons-bundle.json'.

• scanDir (string)

  • Directory to scan for icon usage in your source files.
  • Default: 'src'.

• includes (object)

  • Configuration for force-including icons or icon sets.
  • Use case: Use this to force include icon sets that cannot be found by the static scanner. This is essential when icon names are dynamic, such as those loaded from a database or API at runtime.
  • includes.iconSets (string[])
    • List of icon set prefixes to include entirely (e.g., ['lucide', 'tabler']).
  • includes.icons (string[])
    • Specific icons to include (e.g., ['lucide:home', 'tabler:package']).

• fallback (boolean)

  • Enable or disable fallback to Iconify API when an icon is not found locally.
  • Default: true.

Configuration Example

import { defineConfig } from "vite";
import { sveltekit } from "@sveltejs/kit/vite";
import { svIconify } from "sv-iconify/vite";

export default defineConfig({
    plugins: [
        svIconify({
            sourceDir: "./custom-icons",
            outputPath: "static/icons/icons-bundle.json",
            scanDir: "src",
            includes: {
                iconSets: ["mdi", "carbon"],
                icons: ["lucide:home", "tabler:package"],
            },
        }),
        sveltekit(),
    ],
});

License

MIT

Credits

• Iconify - Icon source
• KawaiiLogos - Logo design inspiration