Using Iconify plugin for Tailwind CSS

Iconify plugin for Tailwind CSS package has several plugins. This documentation covers addIconSelectors plugin.

The Difference

What makes this plugin different from addDynamicIconSelectors()?

• More compact CSS, reusing common code.
• Cleaner icon names.
• You can use the same icon as mask or background image.

Downsides:

• Requires configuration. You must list icon sets you want to use.

HTML

To add icon to HTML, all you have to do is create a <span> element with two class names:

• Class name to render icon as background or mask image.
• Class name with icon name (CSS contains icon data).

Examples:

html<span class="iconify ph--alarm-duotone"></span>
<span class="iconify-color fluent-emoji-flat--alarm-clock"></span>
<span class="iconify carbon--edit-off"></span>

Why two class names? To reduce duplication and make CSS much smaller. One class has only icon data, another reusable class tells the browser how to render that icon data.

Icon class names

Each rendered icon shares most of its rules with other icons. By splitting those rules into separate classes, CSS becomes much smaller.

Icon name selector

Icon name selector sets icon data. Syntax is "{prefix}--{name}", where "{prefix}" is icon set prefix, "{name}" is icon name. Syntax can be easily changed in plugin options.

CSS generated by plugin for an icon:

css.mdi-light--home {
 --svg: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' width='24' height='24'%3E%3Cpath fill='black' d='m16 8.41l-4.5-4.5L4.41 11H6v8h3v-6h5v6h3v-8h1.59L17 9.41V6h-1zM2 12l9.5-9.5L15 6V5h3v4l3 3h-3v8h-5v-6h-3v6H5v-8z'/%3E%3C/svg%3E");
}

Iconify selector

Icon can be rendered as either background image or mask image.

Mask image renders icon in text color. See how monotone icons work in CSS. To render icon as a mask image, add "iconify" selector.

Background image renders icon in color that is set in icon (should be used for things like emojis that have hardcoded palette). To render icon as a background image, add "iconify-color" selector.

Selectors can be easily changed in plugin options.

CSS generated by plugin for reusable selectors:

css.iconify {
 display: inline-block;
 width: 1em;
 height: 1em;
 background-color: currentColor;
 -webkit-mask-image: var(--svg);
 mask-image: var(--svg);
 -webkit-mask-repeat: no-repeat;
 mask-repeat: no-repeat;
 -webkit-mask-size: 100% 100%;
 mask-size: 100% 100%;
}

.iconify-color {
 display: inline-block;
 width: 1em;
 height: 1em;
 background-image: var(--svg);
 background-repeat: no-repeat;
 background-size: 100% 100%;
}

Color and size

To change icon color and size, use color and size class names like you would for any text:

html<span class="iconify ph--alarm-duotone text-red-600 text-2xl"></span>

You can also resize an icon using width and height:

html<span class="iconify-color twemoji--cat-face w-12 h-12"></span>

Make sure width and height are the same because some browsers (Safari) fail to keep proportions when using SVG as a mask image.

If you set option square to false, icons are not square, and you are using custom width and height classes, make sure width/height ratio matches icon's width/height ratio.

See size documentation.

Usage

To add plugin to Tailwind CSS, you need to open tailwind.config.js, import addIconSelectors from @iconify/tailwind and add it to a list of plugins.

Basic usage

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

/** @type {import('tailwindcss').Config} */
module.exports = {
   content: ['./src/*.html'],
   plugins: [
       // Iconify plugin, requires writing list of icon sets to load
       addIconSelectors(['mdi', 'mdi-light']),
   ],
};

Parameter to addIconSelectors is an array of icon sets you want to use.

To avoid generating too many icons, which would take a huge amount of time, you need to tell plugin which icon sets you want to use.

Entry can be an icon set prefix or a custom icon set.

Size and color

See size and color documentation.

Advanced usage

The plugin also accepts an object with options as parameter.

The only required option is prefixes, which is a list of prefixes, same as an array in the example above.

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

/** @type {import('tailwindcss').Config} */
module.exports = {
   content: ['./src/*.html'],
   plugins: [
       // Iconify plugin, requires writing list of icon sets to load
       addIconSelectors({
           // List of prefixes, required
           prefixes: ['mdi', 'mdi-light'],
           
           // All other properties below are optional. This example shows default values.
           // Mask and background selectors
           maskSelector: '.iconify-color',
           backgroundSelector: '.iconify',
           // Icon selector, must have "{prefix}" and "{name}" in it
           iconSelector: '.{prefix}--{name}',
           // Variable name to use for icon data
           varName: 'svg',
           // Scale icons, which sets width/height in background/mask selectors
           scale: 1,
           // Make icons square
           square: true,
           // Extra rules to add to mask and background selectors
           extraMaskRules: {},
           extraBackgroundRules: {},
           // Callback to customise icons (such as change stroke-width, color, etc...).
           // First param is content, second is icon name, third is icon set prefix.
           // Function should return modified content.
           customise: (content, name, prefix) => content,            
       }),
   ],
};

Options

Plugin options:

• prefixes, (string|IconSetOptions)[] - array of icon sets to load.
• maskSelector, string - custom mask selector. Set to empty string to disable it.
• backgroundSelector, string - custom background selector. Set to empty string to disable it.
• iconSelector, string - custom icon selector. Must include "{prefix}" and "{name}".
• varName, string - CSS variable name to use for icon data.
• scale - scales icons. See below.
• square, boolean - makes icons square. Set to false to generate non-square icons.
• extraMaskRules - extra rules to add to mask selector.
• extraBackgroundRules - extra rules to add to background selector.
• customise - callback to customise icon. You can use it to change stroke width, color and so on.

Default values for all options, except prefixes are shown in code sample above. The default value for prefixes is an empty array.

Prefixes list

This plugin requires setting a list of icon sets you want to use, set as either the only parameter to plugin or as prefixes property in options.

You can use it to:

• Select icon sets you want to use.
• Filter icons to render only icons that you need, which improves plugin performance.
• Customise icons.
• Import custom icon sets.

See prefixes option documentation for details and usage examples.

Customise option

Customise option can be used to customise icons.

You can change icon color, stroke width, animation duration and so on.

See customise option documentation for details and usage examples.

Selectors

Options maskSelector and backgroundSelector can be used to customise selectors used for background and mask.

See selectors options documentation for details and usage examples.

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.