Пресет иконок

Используйте любые иконки с помощью чистого CSS для UnoCSS.

TIP

Рекомендуется к прочтению: Иконки в чистом CSS

Следуйте следующим соглашениям для использования иконок

<префикс><коллекция>-<иконка>
<префикс><коллекция>:<иконка>

Например:

html

<!-- Базовая якорная иконка из Phosphor icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- Оранжевый будильник из Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- Большой логотип Vue -->
<div class="i-logos-vue text-3xl" />
<!-- Солнце в светлом режиме, Луна в темном режиме, из Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Твемоджи смеющегося лица, превращается в слезы при наведении -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Наведите

Посмотрите все доступные иконки.

Установка

pnpmyarnnpmbun

bash

pnpm add -D @unocss/preset-icons @iconify-json/[нужная-коллекция]

bash

yarn add -D @unocss/preset-icons @iconify-json/[нужная-коллекция]

bash

npm install -D @unocss/preset-icons @iconify-json/[нужная-коллекция]

bash

bun add -D @unocss/preset-icons @iconify-json/[нужная-коллекция]

Мы используем Iconify в качестве источника данных для иконок. Вам нужно установить соответствующий набор иконок в devDependencies, следуя шаблону @iconify-json/*. Например, @iconify-json/mdi для Material Design Icons, @iconify-json/tabler для Tabler. Вы можете обратиться к Icônes или Iconify для просмотра всех доступных коллекций.

import presetIcons from '@unocss/preset-icons'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({ /* параметры */ }),
    // ...другие пресеты
  ],
})

TIP

Этот пресет включен в пакет unocss, вы также можете импортировать его оттуда:

import { presetIcons } from 'unocss'

INFO

Вы также можете использовать этот пресет отдельно в дополнение к существующим UI-фреймворкам для получения иконок в чистом CSS!

Если вы предпочитаете установить все наборы иконок, доступные на Iconify, сразу (~130 МБ):

pnpmyarnnpmbun

bash

pnpm add -D @iconify/json

bash

yarn add -D @iconify/json

bash

npm install -D @iconify/json

bash

bun add -D @iconify/json

Дополнительные свойства

Вы можете предоставить дополнительные CSS-свойства для управления поведением иконок по умолчанию. Ниже приведен пример, как сделать иконки встроенными по умолчанию:

presetIcons({
  extraProperties: {
    'display': 'inline-block',
    'vertical-align': 'middle',
    // ...
  },
})

Режимы переопределения

По умолчанию этот пресет будет выбирать режим рендеринга для каждой иконки на основе её характеристик. Вы можете прочитать больше в этом блоге. В некоторых случаях вы можете явно установить режимы рендеринга для каждой иконки.

?bg для background-img - рендерит иконку как изображение фона
?mask для mask - рендерит иконку как изображение маски

Например, vscode-icons:file-type-light-pnpm, иконка с цветами (svg не содержит currentColor), которая будет рендериться как изображение фона. Используйте vscode-icons:file-type-light-pnpm?mask, чтобы её рендерить как изображение маски и обойти её цвета.

html

<div class="w-full flex items-center justify-center gap-x-4 text-4xl p-2 mt-4">
  <div class="i-vscode-icons:file-type-light-pnpm" />
  <div class="i-vscode-icons:file-type-light-pnpm?mask text-red-300" />
</div>

Настройка коллекций и резолверов иконок

Вы можете предоставить коллекции через @iconify-json/[the-collection-you-want], @iconify/json или используя ваши собственные коллекции с помощью параметра collections в вашей конфигурации UnoCSS.

Браузер

Чтобы загрузить коллекции iconify, вы должны использовать @iconify-json/[the-collection-you-want], а не @iconify/json, так как файл json огромный.

Bundler

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

import presetIcons from '@unocss/preset-icons/browser'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default),
        mdi: () => import('@iconify-json/mdi/icons.json').then(i => i.default),
        logos: () => import('@iconify-json/logos/icons.json').then(i => i.default),
      }
    })
  ]
})

CDN

Или если вы предпочитаете получить их из CDN, вы можете указать параметр cdn, так как с v0.32.10. Мы рекомендуем esm.sh как поставщика CDN.

presetIcons({
  cdn: 'https://esm.sh/'
})

Настройка

Вы также можете предоставить свои собственные коллекции, используя CustomIconLoader или InlineCollection, например, используя InlineCollection:

presetIcons({
  collections: {
    custom: {
      circle: '<svg viewBox="0 0 120 120"><circle cx="60" cy="60" r="50"></circle></svg>',
      /* ... */
    },
    carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default as any),
    /* ... */
  }
})

И тогда вы можете использовать его в вашем html: <span class="i-custom:circle"></span>

Node.js

В Node.js пресет будет искать установленный набор иконок iconify автоматически, поэтому вам не нужно регистрировать коллекции iconify.

Вы также можете предоставить свои собственные коллекции, используя также CustomIconLoader или InlineCollection.

FileSystemIconLoader

Кроме того, вы также можете использовать FileSystemIconLoader для загрузки ваших пользовательских иконок из вашей файловой системы. Вам нужно будет установить пакет @iconify/utils как dev dependency.

import fs from 'node:fs/promises'
// loader helpers
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // key as the collection name
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // load your custom icon lazily
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // your custom loader here. Do whatever you want.
          // for example, fetch from a remote server:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // a helper to load icons from the file system
        // files under `./assets/icons` with `.svg` extension will be loaded as it's file name
        // you can also provide a transform callback to change each icon (optional)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

С v2.1.20 из @iconify/utils вы можете использовать другие пакеты для загрузки иконок от других авторов, используя новую createExternalPackageIconLoader помощь.

WARNING

External packages must include icons.json file with the icons data in IconifyJSON format, which can be exported with Iconify Tools. Check Exporting icon set as JSON package for more details.

Например, вы можете использовать an-awesome-collection или @my-awesome-collections/some-collection для загрузки ваших пользовательских или сторонних иконок:

import { createExternalPackageIconLoader } from '@iconify/utils/lib/loader/external-pkg'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: createExternalPackageIconLoader('an-awesome-collection')
    })
  ]
})

Вы также можете комбинировать его с другими пользовательскими загрузчиками иконок, например:

import { createExternalPackageIconLoader } from '@iconify/utils/lib/loader/external-pkg'
import { defineConfig, presetIcons } from 'unocss'
import { FileSystemIconLoader } from 'unplugin-icons/loaders'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        ...createExternalPackageIconLoader('other-awesome-collection'),
        ...createExternalPackageIconLoader('@my-awesome-collections/some-collection'),
        ...createExternalPackageIconLoader('@my-awesome-collections/some-other-collection'),
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/^<svg /, '<svg fill="currentColor" ')
        )
      }
    })
  ]
})

Настройка иконок

Вы можете настроить все иконки, используя параметр customizations конфигурации.

Доступные функции настройки:

transform: преобразовать исходный svg, будет применяться только при использовании пользовательской коллекции иконок (iconify коллекции исключены).
customize: изменить значения настроек иконок по умолчанию.
iconCustomizer: изменить значения настроек иконок по умолчанию.

Для каждой загруженной иконки настройки будут применяться в этом порядке:

применить transform к исходному svg, если он предоставлен и используется пользовательская коллекция иконок
применить customize с настройками по умолчанию, если они предоставлены
применить iconCustomizer с настройками customize, если они предоставлены

Глобальное преобразование пользовательской иконки

Когда вы загружаете свои пользовательские иконки, вы можете их преобразовать, например, добавив атрибут fill с currentColor:

presetIcons({
  customizations: {
    transform(svg) {
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

С версии 0.30.8 transform предоставляет имена collection и icon:

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // не применяйте fill для этих иконок на этой коллекции
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Глобальная настройка иконки

Когда вы загружаете любую иконку, вы можете настроить общие свойства для всех из них, например, настроить один размер:

presetIcons({
  customizations: {
    customize(props) {
      props.width = '2em'
      props.height = '2em'
      return props
    }
  }
})

Настройка иконки/коллекции

Вы можете настроить каждую иконку, используя параметр iconCustomizer конфигурации.

iconCustomizer будет иметь приоритет над конфигурацией.

iconCustomizer будет применяться ко всем коллекциям, то есть для каждой иконки из пользовательской коллекции, inlined на пользовательских коллекциях или из @iconify.

Например, вы можете настроить iconCustomizer, чтобы изменить все иконки для коллекции или отдельные иконки в коллекции:

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // customize all icons in this collection
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // customize this icon in this collection
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // customize this @iconify icon in this collection
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

Директивы

Вы можете использовать директиву icon() в вашем CSS, чтобы получить метаданные иконки.

css

.icon {
  background-image: icon('i-carbon-sun');
}

WARNING

icon() зависит от @unocss/preset-icons и будет использовать конфигурацию, убедитесь, что вы добавили этот пресет.

Больше информации о директиве icon(), проверьте Директивы.

Опции

scale

Type: number
Default: 1

Масштаб, связанный с текущим размером шрифта (1em).

mode

Type: 'mask' | 'bg' | 'auto'
Default: 'auto'
See: https://antfu.me/posts/icons-in-pure-css

Режим сгенерированных CSS иконок.

TIP

mask - используйте цвет фона и свойство mask для монохромных иконок
bg - используйте изображение фона для иконок, цвета статичные
auto - умный выбор режима между mask и bg для каждой иконки на основе её стиля

prefix

Type: string | string[]
Default: 'i-'

Префикс класса для сопоставления правил иконок.

extraProperties

Type: Record<string, string>
Default: {}

Дополнительные CSS-свойства, применяемые к сгенерированным CSS.

warn

Type: boolean
Default: false

Вывод предупреждения при отсутствии сопоставленных иконок.

iconifyCollectionsNames

Type: string[]
Default: undefined

Дополнительные @iconify-json коллекции для использования. Этот параметр следует использовать, когда есть новые @iconify-json коллекции, не указанные в именах коллекций по умолчанию.

collections

Type: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
Default: undefined

В Node.js окружении пресет будет искать установленный набор иконок iconify автоматически. Когда вы используете в браузере, этот параметр предоставляется для предоставления набора данных с пользовательской загрузкой.

layer

Type: string
Default: 'icons'

Правило слоя.

customizations

Type: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
Default: undefined

Настройки пользовательской иконки.

autoInstall

Type: boolean
Default: false

Автоматически устанавливайте пакет источника иконки, когда обнаруживается использование.

WARNING

Только на node окружении, на browser этот параметр будет проигнорирован.

unit

Type: string
Default: 'em'

Пользовательская единица иконки.

cdn

Type: string
Default: undefined

Загружать иконки из CDN. Должно начинаться с https:// и заканчиваться /.

Рекомендуемые:

https://esm.sh/
https://cdn.skypack.dev/

customFetch

Type: (url: string) => Promise<any>
Default: undefined

Пресет использует ofetch как стандартный fetcher, вы также можете предоставить пользовательскую функцию загрузки для предоставления данных иконки.

processor

Type: (cssObject: CSSObject, meta: Required<IconMeta>) => void
Default: undefined

interface IconMeta {
  collection: string
  icon: string
  svg: string
  mode?: IconsOptions['mode']
}

Процессор для CSS объекта перед строкой. См. пример.

Расширенная настройка пользовательского набора иконок

Когда вы используете этот пресет с вашими пользовательскими иконами, рассмотрите использование аналогичного процесса очистки, как сделано Iconify для любого набора иконок. Все инструменты, которые вам нужны, доступны в Iconify Tools.

Вы можете проверить этот репозиторий, используя этот пресет на Vue 3 проекте: @iconify/tools/@iconify-demo/unocss.

Прочитайте Cleaning up icons статью из Iconify для получения дополнительных сведений.

Вопросы доступности

Когда вы используете иконки, важно учитывать всех ваших потенциальных пользователей. Некоторые из них могут использовать экранные читалки, и им может понадобиться альтернативный текст для понимания, что означает иконка. Вы можете использовать атрибут aria-label, чтобы предоставить описание иконки:

html

<a href="/profile" aria-label="Profile" class="i-ph:user-duotone"></a>

Если иконка является декоративной и не требует альтернативного текста, вы можете использовать aria-hidden="true", чтобы скрыть её от экранных читалков:

html

<a href="/profile">
  <span aria-hidden="true" class="i-ph:user-duotone"></span>
  My Profile
</a>

Существует множество других приемов для предоставления подсказочного текста для экранных читателей, например, Wind3 preset включает sr-only для скрытия элементов визуально, но сохраняя их доступными для экранных читателей.

Вы можете найти некоторые хорошие ресурсы в Интернете о доступности иконок, и иконки CSS ведут себя как шрифты иконок, поэтому вы можете использовать те же техники, что и при использовании шрифтов иконок.

Благодарности

Этот пресет вдохновлен этой проблемой, созданной @husayt.
На основе работы этого PR от @userquin.

Пресет иконок ​

Установка ​

Дополнительные свойства ​

Режимы переопределения ​

Настройка коллекций и резолверов иконок ​

Браузер ​

Bundler ​

CDN ​

Настройка ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

Настройка иконок ​

Глобальное преобразование пользовательской иконки ​

Глобальная настройка иконки ​

Настройка иконки/коллекции ​

Директивы ​

Опции ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

iconifyCollectionsNames ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

Расширенная настройка пользовательского набора иконок ​

Вопросы доступности ​

Благодарности ​

Пресет иконок

Установка

Дополнительные свойства

Режимы переопределения

Настройка коллекций и резолверов иконок

Браузер

Bundler

CDN

Настройка

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

Настройка иконок

Глобальное преобразование пользовательской иконки

Глобальная настройка иконки

Настройка иконки/коллекции

Директивы

Опции

scale

mode

prefix

extraProperties

warn

iconifyCollectionsNames

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

Расширенная настройка пользовательского набора иконок

Вопросы доступности

Благодарности