iconify/plugins/tailwind/README.md

Iconify for Tailwind CSS

This plugin creates CSS for over 150k open source icons.

Browse icons at Iconify to see all icons.

Usage

1. Install packages icon sets.
2. In tailwind.config.js import addDynamicIconSelectors from @iconify/tailwind.

HTML

To use icon in HTML, add class with class name like this: icon-[mdi-light--home]

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

Class name has 3 parts:

• Selectot prefix, which can be set in prefix option of plugin. Default value is icon.
• - to tell Tailwind that class name is not complete.
• [{prefix}--{name}] for icon name, where {prefix} is icon set prefix, {name} is icon name.

In Iconify all icon names use the following format: {prefix}:{name}. Due to limitations of Tailwind CSS, same format cannot be used with plugin, so instead, prefix and name are separated by double dash: {prefix}--{name}.

Color, size, alignment

Monoton icons can change color! See Iconify documentation for longer explanation.

To change icon size or color, change font size or text color, like you would with any text.

Icon color cannot be changed for icons with hardcoded palette, such as most emoji sets or flag icons.

To align icon below baseline, add negative vertical alignment, like this (you can also use Tailwind class for that):

<span class="icon-[mdi--home]" style="vertical-align: -0.125em"></span>

Installing icon sets

Plugin does not include icon sets. You need to install icon sets separately.

To install all 150k+ icons, install @iconify/json as a dev dependency.

If you do not want to install big package, install @iconify-json/ packages for icon sets that you use.

See Iconify icon sets for list of available icon sets and icons.

See Iconify documentation for list of packages.

Tailwind config

Add this to tailwind.config.js:

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

Then in plugins section add addDynamicIconSelectors.

Example:

module.exports = {
	content: ['./src/*.html'],
	theme: {
		extend: {},
	},
	plugins: [
		// Iconify plugin
		addDynamicIconSelectors(),
	],
	presets: [],
};

Options

Plugin accepts options as a second parameter:

• prefix is class name prefix. Default value is icon. Make sure there is no - at the end: it is added in classes, but not in plugin parameter.
• overrideOnly: set to true to generate rules that override only icon data. See below.
• scale: sets the default icon height/width value. Can be set to 0 which removes the default height/width. Default is 1 (1em).
• files: list of custom files for icon sets. Key is icon set prefix, value is location of .json file with icon set in IconifyJSON format.
• iconSet: list of custom icon sets. Key is prefix, value is either icon set data in IconifyJSON format or a synchronous callback that returns IconifyJSON data.

overrideOnly

You can use overrideOnly to load some icons without full rules, such as changing icon on hover when main and hover icons are from the same icon set and have same width/height ratio.

Example of config:

plugins: [
	// `icon-`
    addDynamicIconSelectors(),
	// `icon-hover-`
    addDynamicIconSelectors({
      prefix: "icon-hover",
      overrideOnly: true,
    }),
  ],

and usage in HTML:

<span class="icon-[mdi--arrow-left] hover:icon-hover-[mdi--arrow-right]"></span>

License

This package is licensed under MIT license.

SPDX-License-Identifier: MIT

This license does not apply to icons. Icons are released under different licenses, see each icon set for details. Icons available by default are all licensed under some kind of open-source or free license.

© 2023-PRESENT Vjacheslav Trushkin