Preset Icons

Use qualquer ícone com CSS Puro para UnoCSS.

TIP

Siga as seguintes convenções para usar os ícones

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

Por exemplo:

html

<!-- Um ícone de âncora básico do Phosphor icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- Um alarme laranja do Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- Um logo Vue grande -->
<div class="i-logos-vue text-3xl" />
<!-- Sol no modo claro, Lua no modo escuro, do Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji de risada, muda para lágrima ao passar o mouse -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Passe o mouse

Verifique todos os ícones disponíveis.

Instalação

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]

Usamos o Iconify como nossa fonte de dados de ícones. Você precisa instalar o conjunto de ícones correspondente em devDependencies seguindo o padrão @iconify-json/*. Por exemplo, @iconify-json/mdi para Material Design Icons, @iconify-json/tabler para Tabler. Você pode consultar Icônes ou Iconify para todas as coleções disponíveis.

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

export default defineConfig({
  presets: [
    presetIcons({ /* options */ }),
    // ...other presets
  ],
})

TIP

Este preset está incluído no pacote unocss, você também pode importá-lo de lá:

import { presetIcons } from 'unocss'

INFO

Você também pode usar este preset sozinho como um complemento para seus frameworks de UI existentes para ter ícones em CSS puro!

Se você preferir instalar todos os conjuntos de ícones disponíveis no Iconify de uma vez (~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

Propriedades Extras

Você pode fornecer propriedades CSS extras para controlar o comportamento padrão dos ícones. A seguir está um exemplo de como fazer os ícones serem inline por padrão:

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

Sobrescrevendo Modos

Por padrão, este preset escolherá automaticamente os modos de renderização para cada ícone com base nas características dos ícones. Você pode ler mais neste post do blog. Em alguns casos, você pode querer definir explicitamente os modos de renderização para cada ícone.

?bg para background-img - renderiza o ícone como uma imagem de fundo
?mask para mask - renderiza o ícone como uma imagem de máscara

Por exemplo, vscode-icons:file-type-light-pnpm, um ícone com cores (o svg não contém currentColor) que será renderizado como uma imagem de fundo. Use vscode-icons:file-type-light-pnpm?mask para renderizá-lo como uma imagem de máscara e ignorar suas cores.

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>

Configurando coleções e resolvedores de ícones

Você pode fornecer coleções via @iconify-json/[the-collection-you-want], @iconify/json ou usando suas próprias coleções personalizadas usando a opção collections em sua configuração UnoCSS.

Navegador

Para carregar coleções iconify você deve usar @iconify-json/[the-collection-you-want] e não @iconify/json já que o arquivo json é enorme.

Bundler

Ao usar bundlers, você pode fornecer as coleções usando dynamic imports para que elas sejam empacotadas como chunk assíncrono e carregadas sob demanda.

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

Ou se você preferir buscá-los de um CDN, você pode especificar a opção cdn desde v0.32.10. Recomendamos esm.sh como provedor de CDN.

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

Personalização

Você também pode fornecer suas próprias coleções personalizadas usando CustomIconLoader ou InlineCollection, por exemplo usando 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),
    /* ... */
  }
})

E então, você pode usá-lo em seu html: <span class="i-custom:circle"></span>

Node.js

No Node.js o preset irá procurar automaticamente pelo conjunto de dados iconify instalado, então você não precisa registrar as coleções iconify.

Você também pode fornecer suas próprias coleções personalizadas usando também CustomIconLoader ou InlineCollection.

FileSystemIconLoader

Além disso, você também pode usar FileSystemIconLoader para carregar seus ícones personalizados do seu sistema de arquivos. Você precisará instalar o pacote @iconify/utils como dependência de desenvolvimento.

import fs from 'node:fs/promises'
// helpers de loader
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // chave como o nome da coleção
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // carrega seu ícone personalizado de forma preguiçosa
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // seu loader personalizado aqui. Faça o que quiser.
          // por exemplo, buscar de um servidor remoto:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // um helper para carregar ícones do sistema de arquivos
        // arquivos sob `./assets/icons` com extensão `.svg` serão carregados como seu nome de arquivo
        // você também pode fornecer uma transformação de callback para alterar cada ícone (opcional)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

From @iconify/utils v2.1.20 you can use other packages to load icons from others authors using the new createExternalPackageIconLoader helper.

WARNING

External packages must include icons.json file with the icons data in IconifyJSON format, which can be exported with Iconify Tools. Check Exporting icon set as JSON package for more details.

For example, you can use an-awesome-collection or @my-awesome-collections/some-collection to load your custom or 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')
    })
  ]
})

You can also combine it with other custom icon loaders, for example:

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

You can customize all icons using customizations configuration option.

Available customizations functions:

transform: transform raw svg, will be only applied when using custom icon collection (iconify collections excluded).
customize: change default icon customizations values.
iconCustomizer: change default icon customizations values.

For each loaded icon, the customizations will be applied in this order:

apply transform to raw svg, if provided and using custom icon collection
apply customize with default customizations, if provided
apply iconCustomizer with customize customizations, if provided

Global Custom Icon Transformation

When loading your custom icons, you can transform them, for example adding fill attribute with currentColor:

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

From version 0.30.8 the transform provides the collection and icon names:

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

Global Icon Customization

When loading any icon you can customize common properties to all of them, for example configuring the same size:

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

Icon/Collection Customization

You can customize each icon using iconCustomizer configuration option.

The iconCustomizer will take precedence over configuration.

The iconCustomizer will be applied to any collection, that is, for each icon from custom loader, inlined on custom collections or from @iconify.

For example, you can configure iconCustomizer to change all icons for a collection or individual icons on a collection:

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

Directives

You can use the icon() directive in your CSS to get the metadata of the icon.

css

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

WARNING

icon() depends on @unocss/preset-icons and will use the configuration, make sure you have added this preset.

More about icon() directive, check Directives.

Opções

scale

Tipo: number
Padrão: 1

Escala do ícone.

mode

Tipo: 'mask' | 'background-img' | 'auto'
Padrão: 'auto'

Modo de renderização do ícone.

prefix

Tipo: string
Padrão: 'i-'

Prefixo para as classes de ícones.

extraProperties

Tipo: Record<string, string>
Padrão: {}

Propriedades CSS extras para aplicar aos ícones.

warn

Tipo: boolean
Padrão: false

Habilita avisos para ícones não encontrados.

collections

Tipo: Record<string, (() => Promise<any>) | any>
Padrão: {}

Coleções de ícones personalizadas.

customizations

Tipo: Record<string, (icon: any) => any>
Padrão: {}

Personalizações para ícones específicos.

autoInstall

Tipo: boolean
Padrão: false

Instalação automática das coleções de ícones quando necessário.

layer

Tipo: string
Padrão: 'icons'

Camada CSS para os ícones.

cdn

Tipo: string
Padrão: 'https://esm.sh/'

CDN para carregar as coleções de ícones.

unit

Tipo: string
Padrão: 'em'

Unidade para o tamanho do ícone.

fallback

Tipo: string
Padrão: undefined

Ícone de fallback quando o ícone solicitado não é encontrado.

filter

Tipo: (icon: any) => boolean
Padrão: undefined

Filtro para ícones.

validate

Tipo: (icon: any) => boolean
Padrão: undefined

Função de validação para ícones.

transform

Tipo: (icon: any) => any
Padrão: undefined

Função de transformação para ícones.

customIconLoader

Tipo: (name: string) => Promise<any> | any
Padrão: undefined

Carregador de ícones personalizado.

customIconCustomizer

Tipo: (icon: any) => any
Padrão: undefined

Personalizador de ícones personalizado.

customIconValidator

Tipo: (icon: any) => boolean
Padrão: undefined

Validador de ícones personalizado.

customIconFilter

Tipo: (icon: any) => boolean
Padrão: undefined

Filtro de ícones personalizado.

customIconTransform

Tipo: (icon: any) => any
Padrão: undefined

Transformador de ícones personalizado.

customIconFallback

Tipo: string
Padrão: undefined

Ícone de fallback personalizado.

customIconCDN

Tipo: string
Padrão: undefined

CDN personalizado para ícones.

customIconUnit

Tipo: string
Padrão: undefined

Unidade personalizada para ícones.

customIconLayer

Tipo: string
Padrão: undefined

Camada CSS personalizada para ícones.

customIconPrefix

Tipo: string
Padrão: undefined

Prefixo personalizado para ícones.

customIconExtraProperties

Tipo: Record<string, string>
Padrão: undefined

Propriedades extras personalizadas para ícones.

customIconWarn

Tipo: boolean
Padrão: undefined

Avisos personalizados para ícones.

customIconAutoInstall

Tipo: boolean
Padrão: undefined

Instalação automática personalizada para ícones.

customIconCollections

Tipo: Record<string, (() => Promise<any>) | any>
Padrão: undefined

Coleções personalizadas para ícones.

customIconCustomizations

Tipo: Record<string, (icon: any) => any>
Padrão: undefined

Personalizações personalizadas para ícones.

customIconMode

Tipo: 'mask' | 'background-img' | 'auto'
Padrão: undefined

Modo personalizado para ícones.

customIconScale

Tipo: number
Padrão: undefined

Escala personalizada para ícones.

customIconFilter

Tipo: (icon: any) => boolean
Padrão: undefined

Filtro personalizado para ícones.

customIconValidate

Tipo: (icon: any) => boolean
Padrão: undefined

Validação personalizada para ícones.

customIconTransform

Tipo: (icon: any) => any
Padrão: undefined

Transformação personalizada para ícones.

customIconLoader

Tipo: (name: string) => Promise<any> | any
Padrão: undefined

Carregador personalizado para ícones.

customIconCustomizer

Tipo: (icon: any) => any
Padrão: undefined

Personalizador personalizado para ícones.

customIconValidator

Tipo: (icon: any) => boolean
Padrão: undefined

Validador personalizado para ícones.

customIconFilter

Tipo: (icon: any) => boolean
Padrão: undefined

Filtro personalizado para ícones.

customIconTransform

Tipo: (icon: any) => any
Padrão: undefined

Transformação personalizada para ícones.

customIconFallback

Tipo: string
Padrão: undefined

Fallback personalizado para ícones.

customIconCDN

Tipo: string
Padrão: undefined

CDN personalizado para ícones.

customIconUnit

Tipo: string
Padrão: undefined

Unidade personalizada para ícones.

customIconLayer

Tipo: string
Padrão: undefined

Camada CSS personalizada para ícones.

customIconPrefix

Tipo: string
Padrão: undefined

Prefixo personalizado para ícones.

customIconExtraProperties

Tipo: Record<string, string>
Padrão: undefined

Propriedades extras personalizadas para ícones.

customIconWarn

Tipo: boolean
Padrão: undefined

Avisos personalizados para ícones.

customIconAutoInstall

Tipo: boolean
Padrão: undefined

Instalação automática personalizada para ícones.

customIconCollections

Tipo: Record<string, (() => Promise<any>) | any>
Padrão: undefined

Coleções personalizadas para ícones.

customIconCustomizations

Tipo: Record<string, (icon: any) => any>
Padrão: undefined

Personalizações personalizadas para ícones.

customIconMode

Tipo: 'mask' | 'background-img' | 'auto'
Padrão: undefined

Modo personalizado para ícones.

customIconScale

Tipo: number
Padrão: undefined

Escala personalizada para ícones.

Accessibility Concerns

When using icons, it's important to take all your potential users into account. Some of them might be using screen readers, and they will need an alternative text to understand what an icon means. You can use the aria-label attribute to provide a description of the icon:

html

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

If the icon is purely decorative and doesn't need a text alternative, you can use aria-hidden="true" to hide it from screen readers:

html

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

There are many other techniques to provide hint text for screen-readers, for instance, Wind3 preset includes sr-only to hide elements visually but keep them accessible to screen readers.

You can find some good resources on the web about icons accessibility, and CSS icons behave like icon fonts, so you can use the same techniques as you would with icon fonts.

Credits

This preset is inspired from this issue created by @husayt.
Based on the work of this PR by @userquin.

Preset Icons ​

Instalação ​

Propriedades Extras ​

Sobrescrevendo Modos ​

Configurando coleções e resolvedores de ícones ​

Navegador ​

Bundler ​

CDN ​

Personalização ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

Icon Customizations ​

Global Custom Icon Transformation ​

Global Icon Customization ​

Icon/Collection Customization ​

Directives ​

Opções ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

collections ​

customizations ​

autoInstall ​

layer ​

cdn ​

unit ​

fallback ​

filter ​

validate ​

transform ​

customIconLoader ​

customIconCustomizer ​

customIconValidator ​

customIconFilter ​

customIconTransform ​

customIconFallback ​

customIconCDN ​

customIconUnit ​

customIconLayer ​

customIconPrefix ​

customIconExtraProperties ​

customIconWarn ​

customIconAutoInstall ​

customIconCollections ​

customIconCustomizations ​

customIconMode ​

customIconScale ​

customIconFilter ​

customIconValidate ​

customIconTransform ​

customIconLoader ​

customIconCustomizer ​

customIconValidator ​

customIconFilter ​

customIconTransform ​

customIconFallback ​

customIconCDN ​

customIconUnit ​

customIconLayer ​

customIconPrefix ​

customIconExtraProperties ​

customIconWarn ​

customIconAutoInstall ​

customIconCollections ​

customIconCustomizations ​

customIconMode ​

customIconScale ​

Accessibility Concerns ​

Credits ​

Preset Icons

Instalação

Propriedades Extras

Sobrescrevendo Modos

Configurando coleções e resolvedores de ícones

Navegador

Bundler

CDN

Personalização

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

Icon Customizations

Global Custom Icon Transformation

Global Icon Customization

Icon/Collection Customization

Directives

Opções

scale

mode

prefix

extraProperties

warn

collections

customizations

autoInstall

layer

cdn

unit

fallback

filter

validate

transform

customIconLoader

customIconCustomizer

customIconValidator

customIconFilter

customIconTransform

customIconFallback

customIconCDN

customIconUnit

customIconLayer

customIconPrefix

customIconExtraProperties

customIconWarn

customIconAutoInstall

customIconCollections

customIconCustomizations

customIconMode

customIconScale

customIconFilter

customIconValidate

customIconTransform

customIconLoader

customIconCustomizer

customIconValidator

customIconFilter

customIconTransform

customIconFallback

customIconCDN

customIconUnit

customIconLayer

customIconPrefix

customIconExtraProperties

customIconWarn

customIconAutoInstall

customIconCollections

customIconCustomizations

customIconMode

customIconScale

Accessibility Concerns

Credits