アイコンプリセット

UnoCSS でピュア CSS を使用して任意のアイコンを使用します。

ヒント

アイコンを使用するには、次の規則に従ってください。

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

例

html

<!-- A basic anchor icon from Phosphor icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- An orange alarm from Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- A large Vue logo -->
<div class="i-logos-vue text-3xl" />
<!-- Sun in light mode, Moon in dark mode, from Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji of laugh, turns to tear on hovering -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

ホバー

利用可能なすべてのアイコンを確認するには、こちらをご覧ください。

インストール

pnpmyarnnpm

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]

アイコンのデータソースとして 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 */ }),
    // ...other presets
  ],
})

ヒント

このプリセットは `unocss` パッケージに含まれています。そこからインポートすることもできます。

import { presetIcons } from 'unocss'

情報

このプリセットは単独で、既存のUIフレームワークの補完として使用して、ピュアCSSアイコンを持つことも可能です！

Iconify で利用可能なすべてのアイコンセットを一度にインストールする場合は（約 130MB）、

pnpmyarnnpm

bash

pnpm add -D @iconify/json

bash

yarn add -D @iconify/json

bash

npm install -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`、または `UnoCSS` 設定の `collections` オプションを使用してカスタムコレクションを指定できます。

ブラウザ

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

バンドラー

バンドラーを使用する場合、`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 class="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 { defineConfig, presetIcons } from 'unocss'

// loader helpers
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'

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

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

警告

外部パッケージには、`IconifyJSON` 形式の `icons` データを含む `icons.json` ファイルが含まれている必要があります。これは、Iconify ツールを使用してエクスポートできます。詳細については、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`: raw `svg` を変換します。カスタムアイコンコレクション（`iconify` コレクションは除く）を使用する場合にのみ適用されます。
`customize`: デフォルトのアイコンカスタマイズ値を変更します。
`iconCustomizer`: デフォルトのアイコンカスタマイズ値を変更します。

ロードされた各アイコンに対して、カスタマイズは次の順序で適用されます。

カスタムアイコンコレクションを使用していて、提供されている場合は、raw `svg` に `transform` を適用します。
提供されている場合は、デフォルトのカスタマイズを使用して `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) {
      // do not apply fill to this icons on this collection
      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` ローダー、`inlined`、`custom collections`、または `@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'
      }
    }
  }
})

ディレクティブ

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

css

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

警告

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

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

オプション

scale

型: number
デフォルト: 1

現在のフォントサイズ (1em) に対する倍率。

mode

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

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

ヒント

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

prefix

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

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

extraProperties

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

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

warn

型: boolean
デフォルト: false

見つからないアイコンが一致したときに警告を出力します。

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環境でのみ有効で、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オブジェクトを処理します。例を参照してください。

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

このプリセットをカスタムアイコンで使用する場合、Iconify が行うようなクリーンアッププロセスをすべてのアイコンセットに対して行うことを検討してください。必要なツールはすべてIconify Toolsで利用できます。

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

アイコンのクリーンアップの記事（Iconify）で詳細を確認してください。

クレジット

このプリセットは、このissue（@husayt作成）に触発されています。
このPR（@userquin作成）に基づいています。

アイコン プリセット ​

インストール ​

追加プロパティ ​

モードのオーバーライド ​

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

ブラウザ ​

バンドラー ​

CDN ​

カスタマイズ ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

アイコンのカスタマイズ ​

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

グローバルアイコンカスタマイズ ​

アイコン/コレクションのカスタマイズ ​

ディレクティブ ​

オプション ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

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

クレジット ​

アイコンプリセット

インストール

追加プロパティ

モードのオーバーライド

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

ブラウザ

バンドラー

CDN

カスタマイズ

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

アイコンのカスタマイズ

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

グローバルアイコンカスタマイズ

アイコン/コレクションのカスタマイズ

ディレクティブ

オプション

scale

mode

prefix

extraProperties

warn

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

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

クレジット