Icons preset

Använd vilken ikon som helst med ren CSS för UnoCSS.

Källkod

TIP

Rekommenderad läsning: Icons in Pure CSS

Följ följande konventioner för att använda ikonerna

• <prefix><samling>-<ikon>
• <prefix><samling>:<ikon>

Till exempel:

<!-- En grundläggande ankare-ikon från Phosphor-ikoner -->
<div class="i-ph-anchor-simple-thin" />
<!-- En orange varning från Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- En stor Vue-logotyp -->
<div class="i-logos-vue text-3xl" />
<!-- Sol i ljust läge, måne i mörkt läge, från Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji av skratt, blir till tår vid hovring -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Hovra den

Kontrollera alla tillgängliga ikoner.

Installera

pnpm

pnpm add -D @unocss/preset-icons @iconify-json/[den-samling-du-vill-ha]

yarn

yarn add -D @unocss/preset-icons @iconify-json/[den-samling-du-vill-ha]

npm

npm install -D @unocss/preset-icons @iconify-json/[den-samling-du-vill-ha]

bun

bun add -D @unocss/preset-icons @iconify-json/[den-samling-du-vill-ha]

Vi använder Iconify som vår datakälla för ikoner. Du behöver installera motsvarande ikonuppsättning i devDependencies genom att följa @iconify-json/*-mönstret. Till exempel, @iconify-json/mdi för Material Design Icons, @iconify-json/tabler för Tabler. Du kan se Icônes eller Iconify för alla tillgängliga samlingar.

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

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

TIP

Denna preset ingår i unocss-paketet, du kan också importera den därifrån:

import { presetIcons } from 'unocss'

INFO

Du kan också använda denna preset ensam som ett komplement till dina befintliga UI-ramverk för att ha ikoner i ren CSS!

Om du föredrar att installera alla ikonuppsättningar som finns tillgängliga på Iconify på en gång (~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

Extra egenskaper

Du kan tillhandahålla extra CSS-egenskaper för att kontrollera ikonernas standardbeteende. Följande är ett exempel på hur man gör ikoner inlinje som standard:

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

Lägen-åsidosättanden

Som standard kommer denna preset att välja renderingslägen automatiskt för varje ikon baserat på ikonernas egenskaper. Du kan läsa mer i detta blogginlägg. I vissa fall kan du vilja explicit ställa in renderingslägen för varje ikon.

• ?bg för background-img - renderar ikonen som en bakgrundsbild
• ?mask för mask - renderar ikonen som en maskbild

Till exempel, vscode-icons:file-type-light-pnpm, en ikon med färger (den svg innehåller inte currentColor) som kommer att renderas som en bakgrundsbild. Använd vscode-icons:file-type-light-pnpm?mask för att rendera den som en maskbild och kringgå dess färger.

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

Konfigurera samlingar och ikonupplösare

Du kan tillhandahålla samlingar via @iconify-json/[den-samling-du-vill-ha], @iconify/json eller använda dina egna anpassade med collections-alternativet i din UnoCSS-konfiguration.

Webbläsare

För att ladda iconify-samlingar bör du använda @iconify-json/[den-samling-du-vill-ha] och inte @iconify/json eftersom json-filen är enorm.

Buntare

När du använder buntare kan du tillhandahålla samlingarna med hjälp av dynamiska importer så att de kommer att buntas som asynkron chunk och laddas vid behov.

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

Eller om du föredrar att hämta dem från CDN kan du ange cdn-alternativet sedan v0.32.10. Vi rekommenderar esm.sh som CDN-leverantör.

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

Anpassning

Du kan också tillhandahålla dina egna anpassade samlingar med hjälp av CustomIconLoader eller InlineCollection, till exempel med 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),
    /* ... */
  }
})

Och sedan kan du använda den i din html: <span class="i-custom:circle"></span>

Node.js

I Node.js kommer preset att söka efter den installerade iconify-dataset automatiskt, så du behöver inte registrera iconify-samlingarna.

Du kan också tillhandahålla dina egna anpassade samlingar med hjälp av också CustomIconLoader eller InlineCollection.

FileSystemIconLoader

Dessutom kan du också använda FileSystemIconLoader för att ladda dina anpassade ikoner från ditt filsystem. Du behöver installera @iconify/utils-paketet som dev dependency.

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

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // nyckel som samlingens namn
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // ladda din anpassade ikon i efterhand
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // din anpassade loader här. Gör vad du vill.
          // till exempel, hämta från en fjärrserver:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // en hjälpfunktion för att ladda ikoner från filsystemet
        // filer under `./assets/icons` med `.svg`-extension kommer att laddas som dess filnamn
        // du kan också tillhandahålla en transform-återuppringning för att ändra varje ikon (valfritt)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

Från @iconify/utils v2.1.20 kan du använda andra paket för att ladda ikoner från andra författare med hjälp av den nya createExternalPackageIconLoader-hjälpen.

VARNING

Externa paket måste inkludera icons.json-fil med icons-data i IconifyJSON-format, vilket kan exporteras med Iconify Tools. Kontrollera Exporting icon set as JSON package för mer information.

Till exempel kan du använda an-awesome-collection eller @my-awesome-collections/some-collection för att ladda dina anpassade eller tredjepartsikoner:

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

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

Du kan också kombinera det med andra anpassade ikonladdare, till exempel:

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

Ikonanpassningar

Du kan anpassa alla ikoner med hjälp av customizations-konfigurationsalternativet.

Tillgängliga anpassningsfunktioner:

• transform: transformera rå svg, kommer endast att tillämpas vid användning av custom-ikonsamling (iconify-samlingar exkluderade).
• customize: ändra standardvärden för ikonanpassningar.
• iconCustomizer: ändra standardvärden för ikonanpassningar.

För varje laddad ikon kommer anpassningarna att tillämpas i denna ordning:

• tillämpa transform på rå svg, om tillhandahållen och använder anpassad ikonsamling
• tillämpa customize med standardanpassningar, om tillhandahållen
• tillämpa iconCustomizer med customize-anpassningar, om tillhandahållen

Global anpassad ikontransformation

När du laddar dina anpassade ikoner kan du transformera dem, till exempel lägga till fill-attribut med currentColor:

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

Från version 0.30.8 tillhandahåller transform collection- och icon-namnen:

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // tillämpa inte fill på dessa ikoner i denna samling
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Global ikonanpassning

När du laddar någon ikon kan du anpassa vanliga egenskaper till alla, till exempel konfigurera samma storlek:

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

Ikon/Samlingsanpassning

Du kan anpassa varje ikon med hjälp av iconCustomizer-konfigurationsalternativet.

iconCustomizer har företräde framför konfiguration.

iconCustomizer kommer att tillämpas på varje samling, det vill säga för varje ikon från custom-loader, inlined på anpassade samlingar eller från @iconify.

Till exempel kan du konfigurera iconCustomizer för att ändra alla ikoner för en samling eller enskilda ikoner i en samling:

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // anpassa alla ikoner i denna samling
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // anpassa denna ikon i denna samling
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // anpassa denna @iconify-ikon i denna samling
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

Direktiv

Du kan använda icon()-direktivet i din CSS för att få ikonens metadata.

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

WARNING

icon() beror på @unocss/preset-icons och kommer att använda konfigurationen, se till att du har lagt till denna preset.

Mer om icon()-direktivet, kontrollera Directives.

Alternativ

scale

• Typ: number
• Standard: 1

Skala relaterat till aktuell teckenstorlek (1em).

mode

• Typ: 'mask' | 'bg' | 'auto'
• Standard: 'auto'
• Se: https://antfu.me/posts/icons-in-pure-css

Läge för genererade CSS-ikoner.

TIP

• mask - använd bakgrundsfärg och mask-egenskapen för monokroma ikoner
• bg - använd bakgrundsbild för ikonerna, färgerna är statiska
• auto - bestäm smartt läge mellan mask och bg per ikon baserat på dess stil

prefix

• Typ: string | string[]
• Standard: 'i-'

Klassprefix för matchande ikonregler.

extraProperties

• Typ: Record<string, string>
• Standard: {}

Extra CSS-egenskaper som tillämpas på den genererade CSS:en.

warn

• Typ: boolean
• Standard: false

Emit varning när saknade ikoner matchas.

iconifyCollectionsNames

• Typ: string[]
• Standard: undefined

Ytterligare @iconify-json-samlingar att använda. Detta alternativ bör användas när det finns nya @iconify-json-samlingar som inte listas i standardpresets samlingarnamn.

collections

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

I Node.js-miljö kommer preset att söka efter den installerade iconify-dataset automatiskt. När du använder i webbläsaren tillhandahålls detta alternativ för att tillhandahålla dataset med anpassad laddningsmekanism.

layer

• Typ: string
• Standard: 'icons'

Regellager.

customizations

• Typ: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
• Standard: undefined

Anpassad ikonanpassning.

autoInstall

• Typ: boolean
• Standard: false

Installera automatiskt ikonkällspaket när användningen upptäcks.

WARNING

Endast i node-miljö, i browser kommer detta alternativ att ignoreras.

unit

• Typ: string
• Standard: 'em'

Anpassad ikonenhet.

cdn

• Typ: string
• Standard: undefined

Ladda ikoner från CDN. Ska börja med https:// och sluta med /.

Rekommenderas:

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

customFetch

• Typ: (url: string) => Promise<any>
• Standard: undefined

Preset använde ofetch som standard fetcher, du kan också anpassa fetch-funktion för att tillhandahålla ikondata.

processor

• Typ: (cssObject: CSSObject, meta: Required<IconMeta>) => void
• Standard: undefined

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

Processor för CSS-objekt före stringifiering. Se exempel.

Avancerad rensning av anpassad ikonuppsättning

När du använder denna preset med dina anpassade ikoner, överväg att använda en rensningsprocess liknande den som görs av Iconify för alla ikonuppsättningar. Alla verktyg du behöver finns tillgängliga i Iconify Tools.

Du kan kontrollera detta repo, som använder denna preset i ett Vue 3-projekt: @iconify/tools/@iconify-demo/unocss.

Läs Cleaning up icons-artikeln från Iconify för mer information.

Tillgänglighetsproblem

När du använder ikoner är det viktigt att ta hänsyn till alla dina potentiella användare. Vissa av dem kan använda skärmläsare och de kommer att behöva en alternativ text för att förstå vad en ikon betyder. Du kan använda aria-label-attributet för att tillhandahålla en beskrivning av ikonen:

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

Om ikonen är rent dekorativ och inte behöver en textalternativ kan du använda aria-hidden="true" för att dölja den från skärmläsare:

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

Det finns många andra tekniker för att tillhandahålla ledtrådstext för skärmläsare, till exempel inkluderar Wind3 preset sr-only för att dölja element visuellt men hålla dem tillgängliga för skärmläsare.

Du kan hitta några bra resurser på webben om ikontillgänglighet, och CSS-ikoner beter sig som ikontypsnitt, så du kan använda samma tekniker som du skulle göra med ikontypsnitt.

Erkännanden

• Denna preset är inspirerad av denna issue skapad av @husayt.
• Baserat på arbetet i denna PR av @userquin.