Icons preset

UnoCSSでPure CSSとして任意のアイコンを利用できます。

TIP

以下の命名規則でアイコンを利用できます：

<prefix><collection>-<icon>
<prefix><collection>:<icon>

例：

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" />
<!-- 笑顔のTwemoji、ホバーで涙顔に変化 -->
<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/[the-collection-you-want]

bash

yarn add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

bash

npm install -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

bash

bun add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

Iconifyをアイコンのデータソースとして利用しています。@iconify-json/*パターンで該当するアイコンセットをdevDependenciesにインストールしてください。例：Material Design Icons用は@iconify-json/mdi、Tabler用は@iconify-json/tabler。すべてのコレクションはIcônesやIconifyで確認できます。

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

export default defineConfig({
  presets: [
    presetIcons({ /* options */ }),
    // ...他のプリセット
  ],
})

TIP

このプリセットはunocssパッケージに含まれており、そこからもインポートできます：

import { presetIcons } from 'unocss'

INFO

このプリセット単体でも、既存のUIフレームワークにPure CSSアイコンを追加する用途で利用できます！

Iconifyの全アイコンセットを一括インストールしたい場合（約130MB）：

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：マスク画像として描画

例：色付きアイコン（svgにcurrentColorが含まれない）はデフォルトで背景画像として描画されます。?maskを付けるとマスク画像として描画され、色を上書きできます。

コレクション・アイコンリゾルバーの設定

@iconify-json/[the-collection-you-want]や@iconify/json、または独自のコレクションをcollectionsオプションで指定できます。

ブラウザ

iconifyコレクションを読み込む場合は@iconify/jsonではなく@iconify-json/[the-collection-you-want]を使ってください。

バンドラー

バンドラー利用時はdynamic importsでコレクションを指定すると、非同期チャンクとして必要時に読み込まれます。

CDN

CDNから取得したい場合はcdnオプションを指定します（v0.32.10以降）。esm.sh推奨。

カスタマイズ

CustomIconLoaderやInlineCollectionで独自コレクションも指定可能です。

Node.js

Node.jsではインストール済みのiconifyデータセットを自動で検索します。独自コレクションもCustomIconLoaderやInlineCollectionで指定可能です。

FileSystemIconLoader

FileSystemIconLoaderでファイルシステムからカスタムアイコンを読み込めます。@iconify/utilsパッケージが必要です。

ExternalPackageIconLoader

@iconify/utils v2.1.20以降、createExternalPackageIconLoaderで他作者のパッケージからも読み込めます。

WARNING

外部パッケージはicons.jsonファイル（IconifyJSON形式）が必要です。詳細はJSONパッケージとしてエクスポートを参照。

アイコンカスタマイズ

customizationsオプションで全アイコンをカスタマイズできます。

transform：生のsvgを変換（カスタムコレクションのみ）
customize：デフォルトカスタマイズ値を変更
iconCustomizer：コレクション・アイコンごとにカスタマイズ

ディレクティブ

CSSでicon()ディレクティブを使い、アイコンのメタデータを取得できます。

css

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

WARNING

icon()は@unocss/preset-iconsに依存します。必ずこのプリセットを追加してください。

オプション

scale

型: number
デフォルト: 1

フォントサイズ（1em）に対するスケール。

mode

型: 'mask' | 'bg' | 'auto'
デフォルト: 'auto'
詳細: https://antfu.me/posts/icons-in-pure-css

生成されるCSSアイコンのモード。

TIP

mask：単色アイコンに背景色とmaskプロパティを使用
bg：背景画像として描画（色は固定）
auto：アイコンのスタイルに応じて自動判定

prefix

型: string | string[]
デフォルト: 'i-'

アイコンルールにマッチするクラスプレフィックス。

extraProperties

型: Record<string, string>
デフォルト: {}

生成されるCSSに適用される追加CSSプロパティ。

warn

型: boolean
デフォルト: false

マッチしないアイコンがあった場合に警告を出す。

iconifyCollectionsNames

型: string[]
デフォルト: undefined

追加の@iconify-jsonコレクションを利用。

collections

型: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
デフォルト: undefined

Node.js環境ではインストール済みのiconifyデータセットを自動検索。ブラウザではカスタムローディング機構を指定。

layer

型: string
デフォルト: 'icons'

ルールレイヤー。

customizations

型: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
デフォルト: undefined

カスタムアイコンカスタマイズ。

autoInstall

型: boolean
デフォルト: false

アイコンソースパッケージの自動インストール（node環境のみ）。

unit

型: string
デフォルト: 'em'

カスタムアイコン単位。

cdn

型: string
デフォルト: undefined

CDNからアイコンを読み込む。https://で始まり/で終わる必要あり。

推奨：

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

customFetch

型: (url: string) => Promise<any>
デフォルト: undefined

デフォルトはofetch。独自のフェッチ関数も指定可能。

processor

型: (cssObject: CSSObject, meta: Required<IconMeta>) => void
デフォルト: undefined

CSSオブジェクトの文字列化前に処理を行うプロセッサ。

高度なカスタムアイコンセットのクリーンアップ

カスタムアイコン利用時はIconify同様のクリーンアップを推奨。Iconify Toolsで利用可能。

アクセシビリティ配慮

アイコン利用時はスクリーンリーダー利用者も考慮しましょう。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>

クレジット

このプリセットは@husaytによるこのissueにインスパイアされています。
@userquinによるこのPRの成果物です。

Icons preset ​

インストール ​

追加プロパティ ​

モードの上書き ​

コレクション・アイコンリゾルバーの設定 ​

ブラウザ ​

バンドラー ​

CDN ​

カスタマイズ ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

アイコンカスタマイズ ​

ディレクティブ ​

オプション ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

iconifyCollectionsNames ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

高度なカスタムアイコンセットのクリーンアップ ​

アクセシビリティ配慮 ​

クレジット ​

Icons preset

インストール

追加プロパティ

モードの上書き

コレクション・アイコンリゾルバーの設定

ブラウザ

バンドラー

CDN

カスタマイズ

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

アイコンカスタマイズ

ディレクティブ

オプション

scale

mode

prefix

extraProperties

warn

iconifyCollectionsNames

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

高度なカスタムアイコンセットのクリーンアップ

アクセシビリティ配慮

クレジット