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.

Plugins

This documentation covers plugin for Tailwind 4.

For an older Tailwind 3 plugin, see Tailwind 3 plugin documentation. It works with Tailwind 4 too, currently has more options than new plugin, but requires creating a config file.

Installation

To install plugin, add @iconify/tailwind4 as dev dependency:

npm i -D @iconify/tailwind4

Plugin does not include icons. You need to add icon sets you want to use.

To add all open source icon sets, add @iconify/json as dev dependency:

npm i -D @iconify/json

You can also install only icon sets that you want to use by installing @iconify-json/{prefix} dependencies (where "{prefix}" is icon set prefix), such as @iconify-json/mdi-light.

See icon data documentation.

Basic usage

Add this to your CSS:

css@plugin "@iconify/tailwind4";

To use icons, add dynamic selector for icon, such as

html<span class="icon-[mdi-light--home]"></span>

Browse or search icons at Iconify icon sets website, click icon you want to use, in code options select "CSS" -> "Tailwind CSS" and copy code.

Options

Plugin supports several options:

• prefix to set custom icon prefix instead of "icon".
• scale to set default icon size. If you do not set icon size, it will have height of "1em".

Example of configuration:

css@plugin "@iconify/tailwind4" {
 prefix: "iconify";
 scale: 1.2;
}

Clean selectors

There are actually 2 plugins in one:

• Plugin for dynamic selectors, such as in code example above
• Plugin for clean selectors

Plugin for clean selectors uses a cleaner syntax for icons, but requires adding a configuration:

html<span class="iconify mdi-light--home"></span>
<span class="iconify-color vscode-icons--file-type-tailwind"></span>

What configuration is required?

You need to specify what icon sets you want to render.

This is done by setting list of prefixes:

css@plugin "@iconify/tailwind4" {
 prefixes: mdi-light, vscode-icons;
}

Extra class name

Each icon has 2 class names:

• Class name for icon, such as "mdi-light--home".
• Class name for rendering mode: "iconify" or "iconify-color" (can be configured).

All icons share same rules, except for image URL.

To avoid duplication, common rules were split into utility classes. Additionally, this allows you to choose how icon is rendered:

• "iconify" renders an icon as a mask image, so icon uses same color as text. To change icon color, change text color. This is used for icons without hardcoded palette.
• "iconify-color" renders an icon as a background image. This is used for icons with hardcoded palette.

Why is config required?

Why is it needed?

Tailwind CSS works by finding class names in your code and rendering CSS for those class names.

When working with dynamic class names, such as "icon-[mdi-light--home]", Tailwind CSS finds all such class names and passes them to a plugin to generate CSS. That means plugin knows which icons are used and loads only required icons.

However, when using plain class names, such as "mdi-light--home", Tailwind CSS requires a plugin to generate CSS for all possible class names first, before finding class names in your project, then it removes unused class names. That means plugin must generate CSS for every single icon that might exist.

Generating CSS for every single icon is not a fast process. With over 200,000 icons available, it might take a lot of time. Then Tailwind CSS keeps it all in memory, which might cause Tailwind CSS to run out of memory. To avoid that, you must specify list of icon sets you want to use.