Iconify в Vue 3 — интеграция и лучшие практики

Кратко

Iconify — это универсальная коллекция SVG-иконок и набор инструментов для их использования в веб-приложениях. В статье показано, как подключить Iconify в Vue 3 с помощью пакета @iconify/vue и альтернативного подхода через unplugin-icons, как избежать проблем рендеринга и как сделать иконки доступными и оптимизированными.

Лучшие веб-приложения используют тексты и изображения вместе — иконки дают визуальные подсказки, ускоряют восприятие интерфейса и повышают вовлечённость. Iconify объединяет множество наборов иконок (Material, Bootstrap, Phosphor и др.) и предоставляет пути интеграции для современных фронтенд‑фреймворков, включая Vue.

Что такое Iconify и когда он нужен

Iconify — это фреймворк для иконок, который предоставляет:

• большую коллекцию SVG-иконок из разных наборов;
• поддержку динамической загрузки иконок и пакетирования;
• интеграции для Vue, React и других инструментов.

Когда использовать Iconify:

• нужны SVG‑иконки разных стилей и наборов;
• требуется гибкая кастомизация цвета/размера/трансформаций в шаблонах Vue;
• нужно снизить ручную работу по управлению SVG-ассетами.

Когда лучше рассмотреть альтернативы:

• если у вас единый фирменный набор и вы хотите полностью контролировать сборку — тогда имеет смысл собрать собственный SVG‑спрайт или компонент‑набор;
• если важен минимальный размер бандла и вы не хотите устанавливать большие JSON‑паки;
• для старых проектов на Vue 2 можно использовать отдельную обёртку @iconify/vue2.

TL;DR: краткая инструкция по установке и быстрому использованию

• Для Vue 3 установите пакет: npm install –save-dev @iconify/vue
• Импортируйте компонент Icon и используйте в шаблоне:
• Если сталкиваетесь с проблемами рендеринга или хотите локально бандлить иконки — используйте unplugin-icons + @iconify/json.
• Не забывайте про доступность: aria-hidden, role, title/desc или скрытые подписи для скрин‑ридеров.

Установка @iconify/vue (Vue 3)

Пакет @iconify/vue — это официальная интеграция Iconify для Vue 3. Установите его в директории приложения:

npm install --save-dev @iconify/vue

Если у вас всё ещё проект на Vue 2, используйте альтернативный пакет:

npm install @iconify/vue2

Важно: официальный пакет @iconify/vue предназначен для Vue 3. Поддержка Vue 2 прекращается, поэтому для новых проектов стоит мигрировать на Vue 3.

Быстрое добавление иконки в компонент Vue

1. Импортируйте компонент Icon в блоке скрипта вашего SFC:

2. Используйте компонент в шаблоне, указывая идентификатор иконки и параметры:

Идентификатор иконки состоит из префикса набора (ph — Phosphor) и имени иконки через двоеточие.

На сайте Iconify можно найти нужную иконку и скопировать её идентификатор или код‑фрагмент для вставки.

Частые проблемы с рендерингом и их причины

Некоторые разработчики сталкиваются с ситуациями, когда иконки не рендерятся корректно, появляются ошибки в DOM или иконки не гидрируются при SSR/пререндеринге. Основные причины:

• порядок инициализации компонентов и загрузки внешних ресурсов;
• динамическая подгрузка иконок после монтирования компонента;
• особенности сборщика (Vite/Rollup/Webpack) и конфигурации плагинов.

Если вы видите ошибки, проверьте последовательность импорта, используете ли вы серверный рендеринг и не блокируют ли политики CSP загрузку ресурсов.

Альтернативный способ: unplugin-icons (локальная компиляция иконок)

unplugin-icons позволяет импортировать иконки как компоненты во время сборки, что устраняет проблемы времени выполнения и упрощает контроль над бандлом.

1. Установите плагин:

npm install unplugin-icons

2. Для проекта на Vite отредактируйте vite.config.js, добавив плагин:

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Icons from 'unplugin-icons/vite'

export default defineConfig({
  plugins: [vue(), Icons()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  }
})

3. (Опционально) Установите наборы иконок в виде JSON, если хотите иметь все наборы локально:

npm i -D @iconify/json

В исходной документации указывается, что полный пакет @iconify/json занимает около 200 МБ. Чтобы уменьшить размер, можно установить только конкретный набор, например Phosphor:

npm i -D @iconify-json/ph

4. Импортируйте иконку как компонент через псевдопуть ~icons:

Эта схема делает иконку частью бандла на этапе сборки, что повышает предсказуемость поведения и исключает динамическую загрузку во время выполнения.

Доступность (a11y) и лучшие практики

Иконки должны быть понятны всем пользователям, включая тех, кто использует вспомогательные технологии. Простые правила:

• Декоративные иконки: добавляйте aria-hidden=”true” и role=”img” при необходимости, чтобы скрин‑ридеры их игнорировали.
• Иконки, несущие смысл: предоставляйте текстовую альтернативу — либо через aria-label, либо совместно с видимым текстом.
• SVG внутри компонента: используйте