アイコンプリセット

UnoCSS (@unocss/preset-icons) のための Pure CSS で任意のアイコンを使用します。

アイコンプリセット

UnoCSS のための Pure CSS で任意のアイコンを使用します。

アイコンを使用するために次の規約に従ってください

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

例えば:

<!-- 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" />

Hover it

利用可能なすべてのアイコンを確認してください。

インストール

::: code-group

pnpm

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

yarn

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

npm

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

bun

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 を参照して、利用可能なすべてのコレクションを確認できます。

uno.config.ts

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）:

::: code-group

pnpm

pnpm add -D @iconify/json

yarn

yarn add -D @iconify/json

npm

npm install -D @iconify/json

bun

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 を使用して、マスク画像としてレンダリングし、色をバイパスします。

<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 を介してコレクションを提供するか、UnoCSS 設定の collections オプションを使用してカスタムコレクションを使用できます。

ブラウザ

iconify コレクションをロードするには、@iconify/json ではなく @iconify-json/[the-collection-you-want] を使用する必要があります。json ファイルは非常に大きいためです。

バンドラー

バンドラーを使用する場合、dynamic imports を使用してコレクションを提供することができ、非同期チャンクとしてバンドルされ、オンデマンドでロードされます。

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 から取得することを好む場合は、v0.32.10 以降で cdn オプションを指定できます。CDN プロバイダーとして esm.sh を推奨します。

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 className="i-custom:circle"></span>

Node.js

Node.js では、プリセットがインストールされた iconify データセットを自動的に検索するため、iconify コレクションを登録する必要はありません。

また、CustomIconLoader または InlineCollection を使用して独自のカスタムコレクションを提供することもできます。

FileSystemIconLoader

さらに、FileSystemIconLoader を使用して、ファイルシステムからカスタムアイコンをロードすることもできます。@iconify/utils パッケージを dev dependency としてインストールする必要があります。

unocss.config.ts

import fs from 'node:fs/promises'
// ローダーヘルパー
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // コレクション名としてのキー
        'my-icons': {
          account: '<svg>{/* ... */}</svg>',
          // カスタムアイコンを遅延ロード
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // カスタムローダーをここに。何でもできます。
          // 例えば、リモートサーバーから取得:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // ファイルシステムからアイコンをロードするためのヘルパー
        // `.svg` 拡張子の `./assets/icons` 以下のファイルはファイル名としてロードされます
        // 各アイコンを変更するための変換コールバックを提供することもできます（オプション）
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

@iconify/utils v2.1.20 から、他の著者からのアイコンをロードするために新しい createExternalPackageIconLoader ヘルパーを使用して他のパッケージを使用できます。

::: warning WARNING 外部パッケージは IconifyJSON 形式で icons データを含む icons.json ファイルを含める必要があります。詳細は JSON パッケージとしてのアイコンセットのエクスポートを確認してください。 :::

例えば、an-awesome-collection または @my-awesome-collections/some-collection を使用してカスタムまたはサードパーティのアイコンをロードできます:

unocss.config.ts

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

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

他のカスタムアイコンローダーと組み合わせることもできます。例えば:

unocss.config.ts

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 を変換します。custom アイコンコレクションを使用する場合のみ適用されます（iconify コレクションは除外されます）。
customize: デフォルトのアイコンカスタマイズ値を変更します。
iconCustomizer: デフォルトのアイコンカスタマイズ値を変更します。

読み込まれた各アイコンに対して、カスタマイズは次の順序で適用されます:

transform を生の svg に適用します（提供されていて、カスタムアイコンコレクションを使用している場合）
デフォルトのカスタマイズで customize を適用します（提供されている場合）
customize カスタマイズで iconCustomizer を適用します（提供されている場合）

グローバルカスタムアイコン変換

カスタムアイコンを読み込む際に、例えば 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 は任意のコレクションに適用されます。つまり、custom ローダーからの各アイコン、custom collections に inlined されたアイコン、または @iconify からのアイコンに適用されます。

例えば、iconCustomizer を設定して、コレクション全体またはコレクション内の個々のアイコンを変更できます:

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // このコレクション内のすべてのアイコンをカスタマイズ
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // このコレクション内のこのアイコンをカスタマイズ
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // このコレクション内のこの @iconify アイコンをカスタマイズ
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

ディレクティブ

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

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

::: warning icon() は @unocss/preset-icons に依存しており、設定を使用します。このプリセットを追加したことを確認してください。 :::

icon() ディレクティブの詳細については、Directives を参照してください。

オプション

scale

型: number
デフォルト: 1

現在のフォントサイズ（1em）に関連するスケール。

mode

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

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

:::tip

mask - 単色アイコンに背景色と mask プロパティを使用
bg - アイコンに背景画像を使用し、色は静的
auto - アイコンのスタイルに基づいて mask と bg の間でスマートにモードを決定

:::

prefix

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

アイコンルールを一致させるためのクラスプレフィックス。

extraProperties

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

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

warn

型: boolean
デフォルト: false

一致しないアイコンがある場合に警告を発します。

iconifyCollectionsNames

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

使用する追加の @iconify-json コレクション。このオプションは、デフォルトのアイコンプリセットコレクション名にリストされていない新しい @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

使用が検出されたときにアイコンソースパッケージを自動インストールします。

:::warning node 環境でのみ、browser ではこのオプションは無視されます。 :::

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

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

文字列化する前の CSS オブジェクトのプロセッサー。詳細は example を参照してください。

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

このプリセットをカスタムアイコンと共に使用する場合、Iconify によって行われるアイコンセットのクリーンアッププロセスに似たプロセスを使用することを検討してください。必要なツールはすべて Iconify Tools にあります。

このリポジトリを確認し、Vue 3 プロジェクトでこのプリセットを使用しています: @iconify/tools/@iconify-demo/unocss。

詳細については、Iconify の Cleaning up icons 記事をお読みください。

アクセシビリティの懸念

アイコンを使用する際には、すべての潜在的なユーザーを考慮することが重要です。中にはスクリーンリーダーを使用している人もおり、アイコンの意味を理解するために代替テキストが必要です。aria-label 属性を使用してアイコンの説明を提供できます:

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

アイコンが純粋に装飾的でテキストの代替が必要ない場合は、aria-hidden="true" を使用してスクリーンリーダーから隠すことができます:

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

スクリーンリーダー用のヒントテキストを提供するための他の多くの技術があります。例えば、Wind3 preset には、要素を視覚的に隠しながらスクリーンリーダーにはアクセス可能にする sr-only が含まれています。

アイコンのアクセシビリティに関する良いリソースがウェブ上にいくつかあり、CSS アイコンはアイコンフォントのように振る舞うため、アイコンフォントで使用するのと同じ技術を使用できます。

クレジット

このプリセットは @husayt によって作成されたこの問題に触発されています。
@userquin によるこの PR の作業に基づいています。

※このページは Nuxt.js 公式ドキュメントの翻訳ページです。

公式ドキュメントの該当ページはこちら：
#