Icons preset​

Use any icon with Pure CSS for UnoCSS.

Source Code

Follow the following conventions to use the icons

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

For example:

<!-- A basic anchor icon from Phosphor icons --><div class="i-ph-anchor-simple-thin" /><!-- An orange alarm from Material Design Icons --><div class="i-mdi-alarm text-orange-400" /><!-- A large Vue logo --><div class="i-logos-vue text-3xl" /><!-- Sun in light mode, Moon in dark mode, from Carbon --><button class="i-carbon-sun dark:i-carbon-moon" /><!-- Twemoji of laugh, turns to tear on hovering --><div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Checkall available icons.

Install​

pnpm add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

yarn add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

npm install -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

bun add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

We useIconify as our data source of icons. You need to install the corresponding icon-set indevDependencies by following the@iconify-json/* pattern. For example,@iconify-json/mdi forMaterial Design Icons,@iconify-json/tabler forTabler. You can refer toIcônes orIconify for all the collections available.

import presetIcons from '@unocss/preset-icons'import { defineConfig } from 'unocss'export default defineConfig({  presets: [    presetIcons({/* options */ }),    // ...other presets  ],})

import { presetIcons } from 'unocss'

If you prefer to install all the icon sets available on Iconify at once (~130MB):

pnpm add -D @iconify/json

yarn add -D @iconify/json

npm install -D @iconify/json

bun add -D @iconify/json

Extra Properties​

You can provide the extra CSS properties to control the default behavior of the icons. The following is an example of making icons inlined by default:

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

Modes Overriding​

By default, this preset will choose the rendering modes automatically for each icon based on the icons' characteristics. You can read more in thisblog post. In some cases, you may want to explicitly set the rendering modes for each icon.

• ?bg forbackground-img - renders the icon as a background image
• ?mask formask - renders the icon as a mask image

For example,vscode-icons:file-type-light-pnpm, an icon with colors (thesvg doesn't containcurrentColor) that will be rendered as a background image. Usevscode-icons:file-type-light-pnpm?mask to render it as a mask image and bypass it's colors.

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

Configuring collections and icons resolvers​

You can provide collections via@iconify-json/[the-collection-you-want],@iconify/json or using your custom ones usingcollections option on yourUnoCSS configuration.

Browser​

To loadiconify collections you should use@iconify-json/[the-collection-you-want] and not@iconify/json since thejson file is huge.

Bundler​

When using bundlers, you can provide the collections usingdynamic imports so they will be bundler as async chunk and loaded on demand.

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​

Or if you prefer to fetch them from CDN, you can specify thecdn option sincev0.32.10. We recommendesm.sh as the CDN provider.

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

Customization​

You can also provide your own custom collections usingCustomIconLoader orInlineCollection, for example usingInlineCollection:

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

And then, you can use it on your html:<span class="i-custom:circle"></span>

Node.js​

InNode.js the preset will search for the installed iconify dataset automatically, so you don't need to register theiconify collections.

You can also provide your own custom collections using alsoCustomIconLoader orInlineCollection.

FileSystemIconLoader​

Additionally, you can also useFileSystemIconLoader to load your custom icons from your file system. You will need to install@iconify/utils package asdev dependency.

import fs from 'node:fs/promises'// loader helpersimport { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'import { defineConfig, presetIcons } from 'unocss'export default defineConfig({  presets: [    presetIcons({      collections: {        // key as the collection name        'my-icons': {          account:'<svg><!-- ... --></svg>',          // load your custom icon lazily          settings: () =>fs.readFile('./path/to/my-icon.svg','utf-8'),          /* ... */        },        'my-other-icons':async (iconName) => {          // your custom loader here. Do whatever you want.          // for example, fetch from a remote server:          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res =>res.text())        },        // a helper to load icons from the file system        // files under `./assets/icons` with `.svg` extension will be loaded as it's file name        // you can also provide a transform callback to change each icon (optional)        '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 newcreateExternalPackageIconLoader helper.

For example, you can usean-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 usingcustomizations configuration option.

Available customizations functions:

• transform: transform rawsvg, will be only applied when usingcustom 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:

• applytransform to rawsvg, if provided and using custom icon collection
• applycustomize with default customizations, if provided
• applyiconCustomizer withcustomize customizations, if provided

Global Custom Icon Transformation​

When loading your custom icons, you can transform them, for example addingfill attribute withcurrentColor:

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

From version0.30.8 thetransform provides thecollection andicon 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 usingiconCustomizer configuration option.

TheiconCustomizer will take precedence over configuration.

TheiconCustomizer will be applied to any collection, that is, for each icon fromcustom loader,inlined oncustom collections or from@iconify.

For example, you can configureiconCustomizer 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 theicon() directive in your CSS to get the metadata of the icon.

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

More abouticon() directive, checkDirectives.

Options​

scale​

• Type:number
• Default:1

Scale related to the current font size (1em).

mode​

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

Mode of generated CSS icons.

prefix​

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

Class prefix for matching icon rules.

extraProperties​

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

Extra CSS properties applied to the generated CSS.

warn​

• Type:boolean
• Default:false

Emit warning when missing icons are matched.

iconifyCollectionsNames​

• Type:string[]
• Default:undefined

Additional@iconify-json collections to use. This option should be used when there are new@iconify-json collections not listed in the default icons preset collection names.

collections​

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

In Node.js environment, the preset will search for the installed iconify dataset automatically. When using in the browser, this options is provided to provide dataset with custom loading mechanism.

layer​

• Type:string
• Default:'icons'

Rule layer.

customizations​

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

Custom icon customizations.

autoInstall​

• Type:boolean
• Default:false

Auto install icon sources package when the usages is detected.

unit​

• Type:string
• Default:'em'

Custom icon unit.

cdn​

• Type:string
• Default:undefined

Load icons from CDN. Should starts withhttps:// and ends with/.

Recommends:

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

customFetch​

• Type:(url: string) => Promise<any>
• Default:undefined

Preset usedofetch as the default fetcher, you can also custom fetch function to provide the icon data.

processor​

• Type:(cssObject: CSSObject, meta: Required<IconMeta>) => void
• Default:undefined

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

Processor for the CSS object before stringify. Seeexample.

Advanced Custom Icon Set Cleanup​

When using this preset with your custom icons, consider using a cleanup process similar to that done byIconify for any icons sets. All the tools you need are available inIconify Tools.

You can check this repo, using this preset on aVue 3 project:@iconify/tools/@iconify-demo/unocss.

ReadCleaning up icons article fromIconify for more details.

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 thearia-label attribute to provide a description of the icon:

<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 usearia-hidden="true" to hide it from screen readers:

<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 includessr-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 fromthis issue created by@husayt.
• Based on the work ofthis PR by@userquin.