Preset Icone

Usa qualsiasi icona con Pure CSS per UnoCSS.

Codice Sorgente

TIP

Lettura consigliata: Icone in Pure CSS

Segui le seguenti convenzioni per usare le icone

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

Ad esempio:

<!-- Un'icona ancora base da Phosphor icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- Un allarme arancione da Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- Un grande logo Vue -->
<div class="i-logos-vue text-3xl" />
<!-- Sole in modalità chiara, Luna in modalità scura, da Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji di risata, diventa lacrime al passaggio del mouse -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Passa sopra

Controlla tutte le icone disponibili.

Installazione

pnpm

pnpm add -D @unocss/preset-icons @iconify-json/[la-collezione-che-desideri]

yarn

yarn add -D @unocss/preset-icons @iconify-json/[la-collezione-che-desideri]

npm

npm install -D @unocss/preset-icons @iconify-json/[la-collezione-che-desideri]

bun

bun add -D @unocss/preset-icons @iconify-json/[la-collezione-che-desideri]

Usiamo Iconify come nostra fonte di dati delle icone. Devi installare il corrispondente set di icone in devDependencies seguendo il pattern @iconify-json/*. Ad esempio, @iconify-json/mdi per Material Design Icons, @iconify-json/tabler per Tabler. Puoi fare riferimento a Icônes o Iconify per tutte le collezioni disponibili.

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

export default defineConfig({
  presets: [
    presetIcons({ /* opzioni */ }),
    // ...altri preset
  ],
})

TIP

Questo preset è incluso nel pacchetto unocss, puoi anche importarlo da lì:

import { presetIcons } from 'unocss'

INFO

Puoi anche usare questo preset da solo come complemento ai tuoi framework UI esistenti per avere icone CSS pure!

Se preferisci installare tutti i set di icone disponibili su Iconify in una volta (~130MB):

pnpm

pnpm add -D @iconify/json

yarn

yarn add -D @iconify/json

npm

npm install -D @iconify/json

bun

bun add -D @iconify/json

Proprietà Extra

Puoi fornire le proprietà CSS extra per controllare il comportamento predefinito delle icone. Quello che segue è un esempio per rendere le icone inline per impostazione predefinita:

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

Sostituzione Modalità

Per impostazione predefinita, questo preset sceglierà automaticamente le modalità di rendering per ogni icona in base alle caratteristiche delle icone. Puoi leggere di più in questo post del blog. In alcuni casi, potresti voler impostare esplicitamente le modalità di rendering per ogni icona.

• ?bg per background-img - rende l'icona come immagine di sfondo
• ?mask per mask - rende l'icona come immagine maschera

Ad esempio, vscode-icons:file-type-light-pnpm, un'icona con colori (l'svg non contiene currentColor) che verrà renderizzata come immagine di sfondo. Usa vscode-icons:file-type-light-pnpm?mask per renderizzarla come immagine maschera e bypassare i suoi colori.

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

Configurazione di collezioni e resolver di icone

Puoi fornire collezioni tramite @iconify-json/[la-collezione-che-desideri], @iconify/json o usando le tue personalizzate usando l'opzione collections nella tua configurazione UnoCSS.

Browser

Per caricare le collezioni iconify dovresti usare @iconify-json/[la-collezione-che-desideri] e non @iconify/json poiché il file json è enorme.

Bundler

Quando usi i bundler, puoi fornire le collezioni usando dynamic imports in modo che vengano bundle come chunk asincrono e caricate su richiesta.

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

Oppure se preferisci recuperarle da CDN, puoi specificare l'opzione cdn da v0.32.10. Raccomandiamo esm.sh come provider CDN.

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

Personalizzazione

Puoi anche fornire le tue collezioni personalizzate usando CustomIconLoader o InlineCollection, ad esempio 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 poi, puoi usarlo nel tuo html: <span class="i-custom:circle"></span>

Node.js

In Node.js il preset cercherà automaticamente il dataset iconify installato, quindi non è necessario registrare le collezioni iconify.

Puoi anche fornire le tue collezioni personalizzate usando anche CustomIconLoader o InlineCollection.

FileSystemIconLoader

Inoltre, puoi anche usare FileSystemIconLoader per caricare le tue icone personalizzate dal tuo file system. Dovrai installare il pacchetto @iconify/utils come dev dependency.

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

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // chiave come nome della collezione
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // carica la tua icona personalizzata in modo lazy
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // il tuo loader personalizzato qui. Fai quello che vuoi.
          // ad esempio, recupera da un server remoto:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // un helper per caricare icone dal file system
        // i file sotto `./assets/icons` con estensione `.svg` verranno caricati come nome del file
        // puoi anche fornire un callback di trasformazione per modificare ogni icona (opzionale)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

Da @iconify/utils v2.1.20 puoi usare altri pacchetti per caricare icone da altri autori usando il nuovo helper createExternalPackageIconLoader.

AVVISO

I pacchetti esterni devono includere un file icons.json con i dati icons nel formato IconifyJSON, che può essere esportato con Iconify Tools. Controlla Esportare set di icone come pacchetto JSON per maggiori dettagli.

Ad esempio, puoi usare an-awesome-collection o @my-awesome-collections/some-collection per caricare le tue icone personalizzate o di terze parti:

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

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

Puoi anche combinarlo con altri loader di icone personalizzati, ad esempio:

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

Personalizzazioni Icone

Puoi personalizzare tutte le icone usando l'opzione di configurazione customizations.

Funzioni di personalizzazione disponibili:

• transform: trasforma svg grezzo, verrà applicato solo quando si usa la collezione di icone custom (collezioni iconify escluse).
• customize: cambia i valori di personalizzazione predefiniti delle icone.
• iconCustomizer: cambia i valori di personalizzazione predefiniti delle icone.

Per ogni icona caricata, le personalizzazioni verranno applicate in questo ordine:

• applica transform a svg grezzo, se fornito e usando collezione di icone personalizzata
• applica customize con personalizzazioni predefinite, se fornito
• applica iconCustomizer con personalizzazioni customize, se fornito

Trasformazione Icona Personalizzata Globale

Quando carichi le tue icone personalizzate, puoi trasformarle, ad esempio aggiungendo l'attributo fill con currentColor:

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

Dalla versione 0.30.8 transform fornisce i nomi collection e icon:

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // non applicare fill a queste icone in questa collezione
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Personalizzazione Icona Globale

Quando carichi qualsiasi icona puoi personalizzare proprietà comuni per tutte, ad esempio configurando la stessa dimensione:

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

Personalizzazione Icona/Collezione

Puoi personalizzare ogni icona usando l'opzione di configurazione iconCustomizer.

iconCustomizer avrà la precedenza sulla configurazione.

iconCustomizer verrà applicato a qualsiasi collezione, cioè per ogni icona dal loader custom, inlined su collezioni personalizzate o da @iconify.

Ad esempio, puoi configurare iconCustomizer per cambiare tutte le icone per una collezione o icone individuali in una collezione:

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // personalizza tutte le icone in questa collezione
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // personalizza questa icona in questa collezione
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // personalizza questa icona @iconify in questa collezione
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

Direttive

Puoi usare la direttiva icon() nel tuo CSS per ottenere i metadati dell'icona.

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

WARNING

icon() dipende da @unocss/preset-icons e userà la configurazione, assicurati di aver aggiunto questo preset.

Maggiori informazioni sulla direttiva icon(), controlla Direttive.

Opzioni

scale

• Tipo: number
• Predefinito: 1

Scala relativa alla dimensione del font corrente (1em).

mode

• Tipo: 'mask' | 'bg' | 'auto'
• Predefinito: 'auto'
• Vedi: https://antfu.me/posts/icons-in-pure-css

Modalità delle icone CSS generate.

TIP

• mask - usa il colore di sfondo e la proprietà mask per icone monocromatiche
• bg - usa l'immagine di sfondo per le icone, i colori sono statici
• auto - decide intelligentemente la modalità tra mask e bg per icona in base al suo stile

prefix

• Tipo: string | string[]
• Predefinito: 'i-'

Prefisso della classe per corrispondere alle regole delle icone.

extraProperties

• Tipo: Record<string, string>
• Predefinito: {}

Proprietà CSS extra applicate al CSS generato.

warn

• Tipo: boolean
• Predefinito: false

Emette un avviso quando vengono corrisposte icone mancanti.

iconifyCollectionsNames

• Tipo: string[]
• Predefinito: undefined

Collezioni @iconify-json aggiuntive da usare. Questa opzione dovrebbe essere usata quando ci sono nuove collezioni @iconify-json non elencate nei nomi delle collezioni predefinite del preset icone.

collections

• Tipo: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
• Predefinito: undefined

Nell'ambiente Node.js, il preset cercherà automaticamente il dataset iconify installato. Quando si usa nel browser, questa opzione viene fornita per fornire dataset con meccanismo di caricamento personalizzato.

layer

• Tipo: string
• Predefinito: 'icons'

Layer della regola.

customizations

• Tipo: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
• Predefinito: undefined

Personalizzazioni icone personalizzate.

autoInstall

• Tipo: boolean
• Predefinito: false

Installa automaticamente il pacchetto delle sorgenti delle icone quando viene rilevato l'uso.

WARNING

Solo nell'ambiente node, nel browser questa opzione verrà ignorata.

unit

• Tipo: string
• Predefinito: 'em'

Unità icona personalizzata.

cdn

• Tipo: string
• Predefinito: undefined

Carica le icone da CDN. Dovrebbe iniziare con https:// e terminare con /.

Raccomandazioni:

• https://esm.sh/
• https://cdn.skypack.dev/

customFetch

• Tipo: (url: string) => Promise<any>
• Predefinito: undefined

Il preset usa ofetch come fetcher predefinito, puoi anche fornire una funzione fetch personalizzata per fornire i dati delle icone.

processor

• Tipo: (cssObject: CSSObject, meta: Required<IconMeta>) => void
• Predefinito: undefined

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

Processore per l'oggetto CSS prima della stringificazione. Vedi esempio.

Pulizia Avanzata Set Icone Personalizzate

Quando usi questo preset con le tue icone personalizzate, considera l'uso di un processo di pulizia simile a quello fatto da Iconify per qualsiasi set di icone. Tutti gli strumenti di cui hai bisogno sono disponibili in Iconify Tools.

Puoi controllare questo repo, usando questo preset su un progetto Vue 3: @iconify/tools/@iconify-demo/unocss.

Leggi l'articolo Pulizia delle icone da Iconify per maggiori dettagli.

Preoccupazioni sull'Accessibilità

Quando usi le icone, è importante tenere conto di tutti i tuoi potenziali utenti. Alcuni di loro potrebbero usare lettori di schermo e avranno bisogno di un testo alternativo per capire cosa significa un'icona. Puoi usare l'attributo aria-label per fornire una descrizione dell'icona:

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

Se l'icona è puramente decorativa e non ha bisogno di un'alternativa testuale, puoi usare aria-hidden="true" per nasconderla ai lettori di schermo:

<a href="/profile">
  <span aria-hidden="true" class="i-ph:user-duotone"></span>
  Il Mio Profilo
</a>

Ci sono molte altre tecniche per fornire testo di suggerimento per i lettori di schermo, ad esempio, il Preset Wind3 include sr-only per nascondere elementi visivamente ma mantenerli accessibili ai lettori di schermo.

Puoi trovare alcune buone risorse sul web sull'accessibilità delle icone, e le icone CSS si comportano come i font delle icone, quindi puoi usare le stesse tecniche che useresti con i font delle icone.

Crediti

• Questo preset è ispirato da questo issue creato da @husayt.
• Basato sul lavoro di questo PR di @userquin.