Package Exports

@achamaro/tailwindcss-iconify-icon
@achamaro/tailwindcss-iconify-icon/tailwind-merge-plugin

Readme

@achamaro/tailwindcss-iconify-icon

This plugin automatically downloads icons from the Iconify API when specified using Tailwind CSS's arbitrary values syntax. No need to install icon sets in advance.

Quick Start

1. Install

npm i -D @achamaro/tailwindcss-iconify-icon

2. Configure

@import "tailwindcss";

@plugin "@achamaro/tailwindcss-iconify-icon";

For Tailwind CSS v3, please refer to Method 2: tailwind.config.

3. Use

<!-- Use Iconify icon -->
<i className="i-[simple-icons/iconify]"></i>

<!-- Use custom SVG -->
<i className="i-[my-custom/icon]"></i>

Installation

npm i -D @achamaro/tailwindcss-iconify-icon

Configuration

The plugin can be configured in two ways:

Method 1: @plugin (CSS-first configuration)

@import "tailwindcss";

@plugin "@achamaro/tailwindcss-iconify-icon";

To specify options:

@import "tailwindcss";

@plugin "@achamaro/tailwindcss-iconify-icon" {
  /* iconDir */
  icon-dir: "src/my/icons";

  /* extraProperties */
  height: 1.5em;
  margin-inline: 4px;
}

Method 2: Config File (tailwind.config)

tailwind.config.ts

import icon from "@achamaro/tailwindcss-iconify-icon";

export default {
  // ...

  plugins: [
    // ...
    icon({
      // options
    }),
  ],
};

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...

  plugins: [
    // ...
    require("@achamaro/tailwindcss-iconify-icon")(),
  ],
};

Options

iconDir / icon-dir

Type: string
Default: {src,app}/assets/icons

Directory for storing icon files. You can place two types of icons:

Icons downloaded from Iconify API
- Example: src/assets/icons/simple-icons/iconify.svg
Custom SVG files
- SVG files placed in src/assets/icons/my-custom/icon.svg can be displayed with i-[my-custom/icon]
- Custom SVGs can be placed in any directory name

If this option is not specified, the default directory is app/assets/icons if the app directory exists, otherwise src/assets/icons.

prefix

Type: string
Default: "i"

Class name prefix

extraProperties

Type: Record<string, string>
Default: { display: "inline-block" }

The following styles are set by default. These styles are basic CSS settings required for proper icon display. You can override these with this parameter.

:where([class^="{prefix}-["], [class*=" {prefix}-["], [class*=":{prefix}-["]) {
  background-size: 100% 100%;
  background-repeat: no-repeat;
  mask-size: 100% 100%;
  mask-repeat: no-repeat;
  height: 1em;
}

In CSS-first configuration, all properties except options are treated as extraProperties.

@plugin "@achamaro/tailwindcss-iconify-icon" {
  /* options */
  icon-dir: "src/my/icons";
  prefix: "i";

  /* extraProperties */
  height: 1.5em;
  margin-inline: 4px;
}

Usage

Syntax

{prefix}-[{icon_set}/{icon_name}]
{prefix}-[{icon_set}/{icon_name}]/{mask | bg}

modifier

Type: mask | bg
- mask: Icon color can be controlled with CSS (color)
- bg: Original icon color is preserved
Default: null

Specifies whether to set the icon as background-image or mask-image.

Example

<!-- Control icon color with CSS (default) -->
<i className="i-[simple-icons/iconify]"></i>

<!-- Preserve original icon color -->
<i className="i-[simple-icons/iconify]/bg"></i>

Other

tailwind merge Plugin

import { extendTailwindMerge } from "tailwind-merge";
import twMergeIconifyIcon from "@achamaro/tailwindcss-iconify-icon/tailwind-merge-plugin";

const twMerge = extendTailwindMerge(twMergeIconifyIcon());

VSCode Extension

TailwindCSS Iconify Icon IntelliSense.

Provides icon name completion and replaces icon names with actual icon images in decorations.

JSPM