Skip to content

Iconify for Tailwind CSS

Iconify plugin for Tailwind CSS makes it easy to use icons in Tailwind CSS.

You can use over 200,000 open source icons and custom icons with minimal code.

Options

There are two plugins, developed by different developers:

Plugins use different syntax, have different options.

For example, here is syntax to use mdi-light:home in HTML:

html<span class="icon-[mdi-light--home]"></span>
Usage with @iconify/tailwind
html<span class="i-mdi-light-home"></span>
Usage with @egoist/tailwindcss-icons

Both plugins can be used with custom icon sets.

The biggest difference is in behavior:

  • @iconify/tailwind uses dynamic class names, so it generates only CSS for icons Tailwind CSS requests.
  • @egoist/tailwindcss-icons generates CSS for all icons in icon set, generating thousands of entries, Tailwind CSS chooses which to include in output.

Documentation

This documentation covers only @iconify/tailwind.

For @egoist/tailwindcss-icons documentation see its repository on GitHub.

Installation

You need to install and configure plugin.

To install it, add @iconify/tailwind as dev dependency:

npm i -D @iconify/tailwind

Then open tailwind.config.js, import addDynamicIconSelectors from @iconify/tailwind and add it to a list of plugins.

Example tailwind.config.js:

jsconst { addDynamicIconSelectors } = require('@iconify/tailwind');

/** @type {import('tailwindcss').Config} */
module.exports = {
   content: ['./src/*.html'],
   plugins: [
       // Iconify plugin
       addDynamicIconSelectors(),
   ],
};

Icon sets

You also need to install icon sets as dev dependencies. You can install either full package @iconify/json or packages for icon sets, you want to use @iconify-json/{prefix}.

See icon data documentation.

For example, if you want to use icon mdi-light:home, install @iconify-json/mdi-light package.

HTML

To use icons in HTML, all you have to do is create <span> element (or any element) with class name that contains icon.

Syntax of class names is this: "icon-[{prefix}--{name}]", where "{prefix}" is icon set prefix, "{name}" is icon name.

Examples:

html<span class="icon-[ph--alarm-duotone]"></span>
<span class="icon-[fluent-emoji-flat--alarm-clock]"></span>
<span class="icon-[carbon--edit-off]"></span>

Make sure prefix and icon name are separated with two hyphens: "--".

Why such a complex syntax? It is because of Tailwind CSS limitations. It can handle dynamic class names only if they are created in format "rule-[value]".

Issues

If everything is done correctly, icons should work.

Possible issues:

Errors when building CSS

If an icon set is missing or icon is missing, the plugin will throw errors.

See error message. If the plugin cannot find an icon set, install dependency. If the plugin cannot find icon, you are using the wrong icon name.

Selectors do not work

You have added class names, built your CSS, but icons do not work?

First, make sure the class name is correct. If it is correct, most likely Tailwind CSS is not seeing your class names. If you are familiar with Tailwind CSS, the process of fixing it is exactly the same as any other missing class name:

  • You can check if your files are scanned.
  • You can add it to safelist in config.

Color and size

To change icon color, change text color. See how monotone icons work in CSS.

By default, icon's height is set to "1em". Width can be different, depending on an icon. To change icon size, set font-size.

You can also set option scale to 0, which will force plugin to not set any size, and use custom size, see plugin options documentation.

Advanced usage

What else can you do with plugin?

The plugin has various options:

  • You can use plugin with custom icon sets.
  • You can change the class name.
  • You can remove duplicate CSS.

See plugin options documentation.

There is also a second plugin included, which behaves a bit differently. Instead of dynamic classes such as "icon-[mdi-light--home]", it can generate CSS with clean classes, such as "icon--mdi-light--home" and reduce duplication.

See clean classnames documentation.

Multiple instances

You can add plugin to the plugin list in Tailwind CSS config multiple times, with different options.

Each addDynamicIconSelectors() entry in the plugin list should have different prefix option to avoid conflicts. The default value for prefix is "icon".

Released under the Apache 2.0 License.