Icons preset

ใช้ไอคอนใดๆ ด้วย Pure CSS สำหรับ UnoCSS

TIP

แนะนำให้อ่าน: Icons in Pure CSS

ทำตาม conventions ต่อไปนี้เพื่อใช้ไอคอน

<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 หัวเราะ เปลี่ยนเป็นน้ำตาเมื่อ hover -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Hover it

ตรวจสอบ ไอคอนทั้งหมดที่มี

การติดตั้ง

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 เป็นแหล่งข้อมูลไอคอน คุณต้องติดตั้ง icon-set ที่เกี่ยวข้องใน devDependencies โดยทำตามรูปแบบ @iconify-json/* ตัวอย่างเช่น @iconify-json/mdi สำหรับ Material Design Icons @iconify-json/tabler สำหรับ Tabler คุณสามารถดู collections ทั้งหมดที่มีได้ที่ Icônes หรือ Iconify

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

export default defineConfig({
  presets: [
    presetIcons({ /* options */ }),
    // ...presets อื่นๆ
  ],
})

TIP

preset นี้รวมอยู่ในแพ็กเกจ unocss คุณสามารถ import จากที่นั่นได้เช่นกัน:

import { presetIcons } from 'unocss'

INFO

คุณยังสามารถใช้ preset นี้เพียงอย่างเดียวเพื่อเสริม UI frameworks ที่มีอยู่ของคุณเพื่อให้มี pure CSS icons!

หากคุณต้องการติดตั้ง icon sets ทั้งหมดที่มีใน 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

Extra Properties

คุณสามารถให้ extra CSS properties เพื่อควบคุมพฤติกรรมเริ่มต้นของไอคอน ต่อไปนี้เป็นตัวอย่างการทำให้ไอคอนอยู่ในบรรทัดโดยค่าเริ่มต้น:

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

Modes Overriding

โดยค่าเริ่มต้น preset นี้จะเลือก rendering modes อัตโนมัติสำหรับแต่ละไอคอนตามลักษณะของไอคอน คุณสามารถอ่านเพิ่มเติมได้ใน blog post นี้ ในบางกรณี คุณอาจต้องการกำหนด rendering modes อย่างชัดเจนสำหรับแต่ละไอคอน

?bg สำหรับ background-img - แสดงไอคอนเป็น background image
?mask สำหรับ mask - แสดงไอคอนเป็น mask image

ตัวอย่างเช่น vscode-icons:file-type-light-pnpm ไอคอนที่มีสี (svg ไม่มี currentColor) จะถูกแสดงเป็น background image ใช้ vscode-icons:file-type-light-pnpm?mask เพื่อแสดงเป็น mask image และข้ามสีของมัน

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>

การกำหนดค่า collections และ icons resolvers

คุณสามารถให้ collections ผ่าน @iconify-json/[the-collection-you-want] @iconify/json หรือใช้ custom ones ของคุณเองโดยใช้ตัวเลือก collections ในการกำหนดค่า UnoCSS ของคุณ

Browser

ในการโหลด iconify collections คุณควรใช้ @iconify-json/[the-collection-you-want] และไม่ใช่ @iconify/json เนื่องจากไฟล์ json มีขนาดใหญ่มาก

Bundler

เมื่อใช้ bundlers คุณสามารถให้ collections โดยใช้ dynamic imports เพื่อให้พวกมันถูก bundle เป็น async chunk และโหลดตามต้องการ

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 provider

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

การปรับแต่ง

คุณยังสามารถให้ custom collections ของคุณเองโดยใช้ 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 preset จะค้นหา iconify dataset ที่ติดตั้งโดยอัตโนมัติ ดังนั้นคุณไม่จำเป็นต้องลงทะเบียน iconify collections

คุณยังสามารถให้ custom collections ของคุณเองโดยใช้ CustomIconLoader หรือ InlineCollection

FileSystemIconLoader

นอกจากนี้ คุณยังสามารถใช้ FileSystemIconLoader เพื่อโหลด custom icons จาก file system ของคุณ คุณจะต้องติดตั้งแพ็กเกจ @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 เป็นชื่อ collection
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // โหลด custom icon ของคุณแบบ lazy
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // custom loader ของคุณที่นี่ ทำอะไรก็ได้ที่คุณต้องการ
          // ตัวอย่างเช่น fetch จาก remote server:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // helper สำหรับโหลด icons จาก file system
        // ไฟล์ภายใต้ `./assets/icons` ที่มีนามสกุล `.svg` จะถูกโหลดตามชื่อไฟล์
        // คุณยังสามารถให้ transform callback เพื่อเปลี่ยนแต่ละ icon (ทางเลือก)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

จาก @iconify/utils v2.1.20 คุณสามารถใช้แพ็กเกจอื่นเพื่อโหลด icons จากผู้เขียนอื่นโดยใช้ helper createExternalPackageIconLoader ใหม่

WARNING

แพ็กเกจภายนอกต้องมีไฟล์ icons.json พร้อมข้อมูล icons ในรูปแบบ IconifyJSON ซึ่งสามารถส่งออกด้วย Iconify Tools ดู Exporting icon set as JSON package สำหรับรายละเอียดเพิ่มเติม

ตัวอย่างเช่น คุณสามารถใช้ an-awesome-collection หรือ @my-awesome-collections/some-collection เพื่อโหลด custom หรือ third party icons:

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

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

คุณยังสามารถรวมกับ custom icon loaders อื่นๆ ตัวอย่างเช่น:

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" ')
        )
      }
    })
  ]
})

Icon Customizations

คุณสามารถปรับแต่งไอคอนทั้งหมดโดยใช้ตัวเลือกการกำหนดค่า customizations

ฟังก์ชัน customizations ที่มี:

transform: แปลง raw svg จะถูกใช้เฉพาะเมื่อใช้ custom icon collection (ไม่รวม iconify collections)
customize: เปลี่ยนค่า default icon customizations
iconCustomizer: เปลี่ยนค่า default icon customizations

สำหรับแต่ละ icon ที่โหลด customizations จะถูกใช้ตามลำดับนี้:

ใช้ transform กับ raw svg หากมีและใช้ custom icon collection
ใช้ customize กับ default customizations หากมี
ใช้ iconCustomizer กับ customize customizations หากมี

Global Custom Icon Transformation

เมื่อโหลด custom icons ของคุณ คุณสามารถแปลงพวกมัน ตัวอย่างเช่นการเพิ่ม attribute fill ด้วย currentColor:

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

จากเวอร์ชัน 0.30.8 transform ให้ชื่อ collection และ icon:

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // ไม่ใช้ fill กับ icons นี้ใน collection นี้
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Global Icon Customization

เมื่อโหลดไอคอนใดๆ คุณสามารถปรับแต่ง properties ทั่วไปสำหรับทั้งหมด ตัวอย่างเช่นการกำหนดขนาดเดียวกัน:

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

Icon/Collection Customization

คุณสามารถปรับแต่งแต่ละ icon โดยใช้ตัวเลือกการกำหนดค่า iconCustomizer

iconCustomizer จะมีความสำคัญเหนือการกำหนดค่า

iconCustomizer จะถูกใช้กับทุก collection นั่นคือสำหรับแต่ละ icon จาก custom loader inlined ใน custom collections หรือจาก @iconify

ตัวอย่างเช่น คุณสามารถกำหนดค่า iconCustomizer เพื่อเปลี่ยนไอคอนทั้งหมดสำหรับ collection หรือไอคอนเฉพาะใน collection:

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // ปรับแต่งไอคอนทั้งหมดใน collection นี้
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // ปรับแต่งไอคอนนี้ใน collection นี้
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // ปรับแต่ง @iconify icon นี้ใน collection นี้
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

Directives

คุณสามารถใช้ directive icon() ใน CSS ของคุณเพื่อรับ metadata ของไอคอน

css

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

WARNING

icon() ขึ้นอยู่กับ @unocss/preset-icons และจะใช้การกำหนดค่านั้น ตรวจสอบให้แน่ใจว่าคุณได้เพิ่ม preset นี้แล้ว

อ่านเพิ่มเติมเกี่ยวกับ directive icon() ที่ Directives

Options

scale

Type: number
Default: 1

Scale ที่เกี่ยวข้องกับขนาดฟอนต์ปัจจุบัน (1em)

mode

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

Mode ของ CSS icons ที่สร้างขึ้น

TIP

mask - ใช้ background color และ property mask สำหรับ monochrome icons
bg - ใช้ background image สำหรับ icons สีคงที่
auto - ตัดสินใจ mode อย่างชาญฉลาดระหว่าง mask และ bg ต่อ icon ตาม style ของมัน

prefix

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

Class prefix สำหรับจับคู่ icon rules

extraProperties

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

Extra CSS properties ที่ใช้กับ CSS ที่สร้างขึ้น

warn

Type: boolean
Default: false

แสดงคำเตือนเมื่อจับคู่ icons ที่ขาดหาย

iconifyCollectionsNames

Type: string[]
Default: undefined

@iconify-json collections เพิ่มเติมที่จะใช้ ตัวเลือกนี้ควรใช้เมื่อมี @iconify-json collections ใหม่ที่ไม่อยู่ใน default icons preset collection names

collections

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

ในสภาพแวดล้อม Node.js preset จะค้นหา iconify dataset ที่ติดตั้งโดยอัตโนมัติ เมื่อใช้ใน browser ตัวเลือกนี้ให้ dataset ด้วยกลไกการโหลดแบบกำหนดเอง

layer

Type: string
Default: 'icons'

Rule layer

customizations

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

Custom icon customizations

autoInstall

Type: boolean
Default: false

ติดตั้ง icon sources package อัตโนมัติเมื่อตรวจพบการใช้งาน

Icons preset ​

การติดตั้ง ​

Extra Properties ​

Modes Overriding ​

การกำหนดค่า collections และ icons resolvers ​

Browser ​

Bundler ​

CDN ​

การปรับแต่ง ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

Icon Customizations ​

Global Custom Icon Transformation ​

Global Icon Customization ​

Icon/Collection Customization ​

Directives ​

Options ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

iconifyCollectionsNames ​

collections ​

layer ​

customizations ​

autoInstall ​

Icons preset

การติดตั้ง

Extra Properties

Modes Overriding

การกำหนดค่า collections และ icons resolvers

Browser

Bundler

CDN

การปรับแต่ง

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

Icon Customizations

Global Custom Icon Transformation

Global Icon Customization

Icon/Collection Customization

Directives

Options

scale

mode

prefix

extraProperties

warn

iconifyCollectionsNames

collections

layer

customizations

autoInstall