Icons preset

UnoCSS용 순수 CSS로 모든 아이콘을 사용하세요.

TIP

다음 규칙을 따라 아이콘을 사용하세요

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

예를 들어:

html

<!-- Phosphor 아이콘의 기본 앵커 아이콘 -->
<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

사용 가능한 모든 아이콘을 확인하세요.

설치

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 */ }),
    // ...other presets
  ],
})

TIP

이 preset은 unocss 패키지에 포함되어 있으며, 거기서도 가져올 수 있습니다:

import { presetIcons } from 'unocss'

INFO

기존 UI 프레임워크의 보완으로 순수 CSS 아이콘을 사용하기 위해 이 preset만 사용할 수도 있습니다!

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',
    // ...
  },
})

모드 재정의

기본적으로 이 preset은 아이콘의 특성에 따라 각 아이콘에 대해 렌더링 모드를 자동으로 선택합니다. 이 블로그 포스트에서 더 자세히 읽을 수 있습니다. 일부 경우에는 각 아이콘에 대해 렌더링 모드를 명시적으로 설정하고 싶을 수 있습니다.

?bg for background-img - 아이콘을 배경 이미지로 렌더링
?mask for 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에서 preset은 설치된 iconify 데이터셋을 자동으로 검색하므로 iconify 컬렉션을 등록할 필요가 없습니다.

CustomIconLoader 또는 InlineCollection을 사용하여 자신만의 사용자 정의 컬렉션을 제공할 수도 있습니다.

FileSystemIconLoader

또한 FileSystemIconLoader를 사용하여 파일 시스템에서 사용자 정의 아이콘을 로드할 수 있습니다. @iconify/utils 패키지를 dev dependency로 설치해야 합니다.

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 헬퍼를 사용하여 다른 작성자의 패키지에서 아이콘을 로드할 수 있습니다.

경고

외부 패키지는 IconifyJSON 형식의 icons 데이터가 포함된 icons.json 파일을 포함해야 하며, 이는 Iconify Tools로 내보낼 수 있습니다. 자세한 내용은 아이콘 세트를 JSON 패키지로 내보내기를 참조하세요.

예를 들어, 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: 기본 아이콘 사용자 정의 값 변경.

로드된 각 아이콘에 대해 사용자 정의는 다음 순서로 적용됩니다:

원시 svg에 transform 적용 (제공되고 사용자 정의 아이콘 컬렉션을 사용하는 경우)
기본 사용자 정의와 함께 customize 적용 (제공되는 경우)
customize 사용자 정의와 함께 iconCustomizer 적용 (제공되는 경우)

전역 사용자 정의 아이콘 변환

사용자 정의 아이콘을 로드할 때 변환할 수 있습니다. 예를 들어 currentColor로 fill 속성 추가:

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() 지시문을 사용하여 아이콘의 메타데이터를 가져올 수 있습니다.

css

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

WARNING

icon()은 @unocss/preset-icons에 의존하며 설정을 사용합니다. 이 preset을 추가했는지 확인하세요.

icon() 지시문에 대한 자세한 내용은 지시문을 참조하세요.

옵션

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, string>
기본값: {}

생성된 CSS에 적용되는 추가 CSS 속성.

warn

타입: boolean
기본값: false

누락된 아이콘이 매치될 때 경고 발생.

iconifyCollectionsNames

타입: string[]
기본값: undefined

사용할 추가 @iconify-json 컬렉션. 이 옵션은 기본 아이콘 preset 컬렉션 이름에 나열되지 않은 새로운 @iconify-json 컬렉션이 있을 때 사용해야 합니다.

collections

타입: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
기본값: undefined

Node.js 환경에서 preset은 설치된 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

Preset은 기본 fetcher로 ofetch를 사용하며, 아이콘 데이터를 제공하기 위해 사용자 정의 fetch 함수를 사용할 수도 있습니다.

processor

타입: (cssObject: CSSObject, meta: Required<IconMeta>) => void
기본값: undefined

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

문자열화 전 CSS 객체에 대한 프로세서. 예시를 참조하세요.

고급 사용자 정의 아이콘 세트 정리

이 preset을 사용자 정의 아이콘과 함께 사용할 때, Iconify가 모든 아이콘 세트에 대해 수행하는 것과 유사한 정리 프로세스를 사용하는 것을 고려하세요. 필요한 모든 도구는 Iconify Tools에서 사용할 수 있습니다.

Vue 3 프로젝트에서 이 preset을 사용하는 이 저장소를 확인할 수 있습니다: @iconify/tools/@iconify-demo/unocss.

자세한 내용은 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 아이콘은 아이콘 폰트처럼 동작하므로 아이콘 폰트와 동일한 기술을 사용할 수 있습니다.

크레딧

이 preset은 @husayt가 생성한 이 이슈에서 영감을 받았습니다.
@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

고급 사용자 정의 아이콘 세트 정리

접근성 고려사항

크레딧