@jcamp/tailwindcss-plugin-icons

Tailwind CSS Icons Plugin

Automatic icon creator for Tailwind CSS

Use any icons with Pure CSS for TailwindCSS.

Recommended reading - @antfu's post titled Icons in Pure CSS.

Follow the following conventions to use the icons

• <prefix>[<collection>-<icon>]
• i-[<collection>-<icon>] - default prefix is i-

For examples:

<!-- 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]"
/>

^{This is powered by pure CSS}

Install

npm i -D @jcamp/tailwindcss-plugin-icons @iconify-json/[the-collection-you-want]

We use Iconify as our data source of icons. You need to install the corresponding iconset in devDependencies by following the @iconify-json/* pattern. For example, @iconify-json/mdi for Material Design Icons, @iconify-json/tabler for Tabler. You can refer to Icônes or Iconify for all the collections available.

Then add the plugin to your tailwind.config.js file:

// tailwind.config.js
const icons = require('@jcamp/tailwindcss-plugin-icons')

module.exports = {
  theme: {
    // ...
  },
  plugins: [
    icons({
      /* options */
    }),
    // ...
  ],
}

// tailwind.config.ts
import type { Config } from 'tailwindcss'
import iconsPlugin from '@jcamp/tailwindcss-plugin-icons'

export default <Partial<Config>>{
  theme: {
    // ...
  },
  plugins: [
    iconsPlugin({
      /* options */
    }),
  ],
}

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

npm i -D @iconify/json

Class names

The structure is i-[<collection>/<name>/<scaling>]

The collection and name can be divided by either a dash - or a slash /. Unfortunately, Tailwind CSS will not pass a colon : properly to the plugin.

If you want to add scaling to the class, you must separate that with a slash /. You can add the unit (px|em|rem) but it is optional. If omitted, it will use the default specified by the config.

<div class="i-[logos-vue/2]" />
<div class="i-[logos/vue/24px]" />
<div class="i-[logos-vue/2rem]" />

JSON collections

As a big fan of Font Awesome, I wanted this to work with their pro collections. It now does. There is a new jsonCollections property in the config that allows you to tell the plugin where to load JSON files from.

jsonCollections: {
  custom: 'json/custom-collection.json',
},

Configuration

Refer to the type definition for all configurations avaliable.

Extra Properties

You can provide the extra CSS properties to control the default behavior of the icons. The following is an example of make 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 this blog post. In some cases, you may want to explicitly set the rendering modes for each icon.

• i-bg- for background-img - renders the icon as a background image
• i-mask- for mask - renders the icon as a mask image

Browser

Because Tailwind does not allow async plugins, see tailwindlabs/tailwindcss#7277, we are using a node process to retrieve the icons, so right now, this will not work in the browser directly.

Customization

Although there is code similar to UnoCSS's customizations, I have not yet had time to write tests for it and confirm it works as expected, so this information will not be in the README for now.

Node.js

In Node.js the preset will search for the installed iconify dataset automatically and so you don't need to register the iconify collections.

Credits

This plugin is heaviliy inspired by and based on the work of UnoCSS Icons Preset created by Anthony Fu

It is also based on some ideas by InfiniteXyy and their work at tailwindcss-iconify. In particular, their idea for spawning a node process to allow async code to work in Tailwinds sync plugin system.

License

MIT License © 2022-PRESENT John Campion