nuxt-icon-skilld

name	nuxt-icon-skilld
description	ALWAYS use when writing code importing "@nuxt/icon". Consult for debugging, best practices, or modifying @nuxt/icon, nuxt/icon, nuxt icon, icon.
metadata	{"version":"2.2.4","generated_by":"Anthropic · Haiku 4.5","generated_at":"2026-06-29T00:00:00.000Z"}

nuxt/icon @nuxt/icon@2.2.4

Tags: latest: 2.2.4

References: package.json • README • Docs • Issues • Releases

Search

Use skilld search "query" -p @nuxt/icon instead of grepping .skilld/ directories. Run skilld search --guide -p @nuxt/icon for full syntax, filters, and operators.

API Changes

This section documents version-specific API changes for @nuxt/icon — prioritize recent major/minor releases.

Configuration & Features

• NEW: icon.cssLayer — v2.2.x added support for TailwindCSS v4, configurable CSS layer injection point via app.config.ts source

• NEW: icon.serverBundle.remote — v2.1 (branded as v1.2 in earlier docs) added remote CDN option with jsdelivr, unpkg, or github-raw providers to avoid bundling collections source

• NEW: icon.serverBundle.externalizeIconsJson — v2.2.x added option to externalize icon JSON files instead of bundling them, requires Node.js v22+ for JSON module imports source

• NEW: customCollections[].recursive — v2.1.0 added nested folder scanning for custom collections, enabling recursive SVG discovery source

• NEW: icon.provider: 'none' — v1.13.0 added provider mode to completely disable runtime fetching and use only client bundle source

• NEW: :customize="false" prop — v1.12.0 allows disabling per-component customization override while preserving global settings source

• NEW: customCollections[].normalizeIconName: false — v1.10.0 enables case-sensitive custom icon names, bypassing kebab-case normalization; defaults to true for backward compatibility but will default to false in a future major version source

• NEW: IconifyJSON as custom collection — v1.12.0 added support for passing raw IconifyJSON objects directly in customCollections instead of only file paths source

Also changed: Icon component in render functions via #components import (documented usage pattern) · Server bundle mode auto auto-selects between local/remote based on deployment environment (Cloudflare Workers defaults to remote) · Client bundle scan option with fine-grained glob control for component scanning · Custom collection imports now handle Nuxt 4 app/assets directory structure · Server endpoint /api/_nuxt_icon/:collection customizable via icon.localApiEndpoint

Dependencies

• BREAKING: Nuxt 4 required — v2.0.0 upgraded to Nuxt v4 as minimum runtime, incompatible with Nuxt 3 source

Best Practices for @nuxt/icon v2.2.4

Overview

@nuxt/icon is a Nuxt module for displaying icons from Iconify and custom collections with flexible rendering modes (CSS or SVG), intelligent bundling strategies, and performance optimizations.

Best Practices

• Use fill="currentColor" in custom SVG icons to generate mask-image CSS rules for dynamic color support — this enables Tailwind color classes like text-white and fill-white to work correctly, as Iconify icons use mask-based rendering by default source source

• Set mode: 'svg' for custom icons requiring dynamic styling — SVG mode inlines the SVG content directly (bypassing CSS mask rendering) and allows currentColor attributes to inherit colors from parent elements source source

• Configure serverBundle: 'remote' to reduce build size when only using Iconify collections — remote mode fetches icons from Iconify API on demand without bundling the full collection data source

• Install @iconify-json/* packages explicitly for icons listed in clientBundle.icons — the module does not fetch icons from the network; it reads from installed packages during build source

• Enable clientBundle.scan: true to auto-detect used icons from your codebase — scanning finds all icon references without manual configuration, though it requires icon collection packages to be installed source

• Set serverBundle: false and provider: 'iconify' for SPA deployments with client-side only icon fetching — this avoids server bundling while fetching icons directly from Iconify API in the browser source

• Wrap icons in <ClientOnly> when using SSR to prevent hydration mismatches — icons may not render identically on server and client, causing hydration warnings; ClientOnly ensures rendering happens only on the client source

• Use CSS mode (default) for production performance — CSS mode generates smaller bundles and is more efficient than SVG mode for most use cases source

• Set customCollections with dir option instead of inline icons for maintainability — directory-based collections allow organizing icons as SVG files with automatic scanning support source

• Configure customize callback for global icon transformations — use this option to apply consistent modifications (colour, stroke-width, viewBox adjustments) to all icons without modifying source files

icon: {
  customize: (svg) => {
    svg.replace('stroke="2"', 'stroke="1.5"');
    return svg;
  };
}

source

• Enable cssWherePseudo: true (default) to reduce CSS specificity conflicts — the :where() pseudo-selector ensures icon styles don't override component styling unexpectedly source

• Use icon aliases for easier refactoring and consistent naming — aliases decouple icon names from implementation, simplifying updates across the codebase

icon: {
  aliases: {
    'arrow': 'mdi:chevron-right',
    'close': 'mdi:close'
  }
}

source

• Set fetchTimeout to 3000–5000ms for reliable fetching in slow networks — default 1500ms may timeout on mobile or high-latency connections source

• Nest custom icons within subdirectories using customCollections with dir — v2.1.0+ automatically scans nested folders, eliminating the need for multiple collection entries source

• Set provider: 'none' with client bundle for offline applications — this disables all network fetching and relies entirely on pre-bundled icons source