@egoist/tailwindcss-icons

If you have installed the full @iconify/json package, using iconsPlugin() alone can make your editor slow because it tries to provide autocomplete for every possible icon.

To avoid this, use dynamicIconsPlugin() alongside iconsPlugin(). This allows you to use any icon from the installed collections using an arbitrary value syntax, without taxing your IDE's autocomplete engine.

```ts
import { dynamicIconsPlugin, iconsPlugin } from '@egoist/tailwindcss-icons'
import type { Config } from 'tailwindcss'

export default {
  plugins: [
    iconsPlugin(), 
    dynamicIconsPlugin()
  ],
} satisfies Config

Usage: <span class="i-[mdi-light--home]"></span>

The plugin requires icon data to function. You have two options:

1. Install all icons: This installs the full @iconify/json collection (approx. 50MB).
2. Install specific collections: Install only the icon sets you need (e.g., Material Design Icons or Lucide) using the @iconify-json/{collection_name} package format. This is more efficient for bundle size and performance.

You can find icon names to search for at https://icones.js.org.

# install every icon:
npm i @iconify/json -D

# or install individual packages like this:
npm i @iconify-json/mdi @iconify-json/lucide -D

For projects using a tailwind.config.ts or tailwind.config.js, import iconsPlugin and getIconCollections from @egoist/tailwindcss-icons.

To optimize performance and avoid scanning all installed packages, explicitly specify the collections you want to use via getIconCollections(). If you omit the collections option, the plugin will attempt to automatically discover all installed individual icon packages.

import { getIconCollections, iconsPlugin } from '@egoist/tailwindcss-icons'
import type { Config } from 'tailwindcss'

export default {
  plugins: [
    iconsPlugin({
      // Select the icon collections you want to use
      collections: getIconCollections(['mdi', 'lucide']),
      
      // To use all icons from @iconify/json (not recommended for performance):
      // collections: getIconCollections("all"),
    }),
  ],
} satisfies Config

In TailwindCSS v4, you can register the plugin directly in your CSS file. You can also pass options using the CSS syntax.

/* Basic usage */
@plugin '@egoist/tailwindcss-icons';

/* Usage with options */
@plugin '@egoist/tailwindcss-icons' {
  scale: 1.5;
}

@plugin '@egoist/tailwindcss-icons';

/* pass options to the plugin */
@plugin '@egoist/tailwindcss-icons' {
  scale: 1.5;
}

Install the plugin as a development dependency using npm:

npm i @egoist/tailwindcss-icons -D

Once configured, use icons by applying a class following the pattern: i-{collection_name}-{icon_name}. The default prefix is i.

<!-- pattern: i-{collection_name}-{icon_name} -->
<span class="i-mdi-home"></span>

You can define your own icons directly within the iconsPlugin configuration by providing an object containing the SVG body and optional dimensions.

```ts
import { iconsPlugin } from '@egoist/tailwindcss-icons'
import type { Config } from 'tailwindcss'

export default {
  plugins: [
    iconsPlugin({
      collections: {
        foo: {
          icons: {
            'arrow-left': {
              // svg body
              body: '<path d="M10 19l-7-7m0 0l7-7m-7 7h18"/>',
              // svg width and height, optional
              width: 24,
              height: 24,
            },
          },
        },
      },
    }),
  ],
} satisfies Config

Usage: <span class="i-foo-arrow-left"></span>

When using iconsPlugin, you can pass an options object to customize the generation behavior:

• collections: A record of IconifyJSONIconsData keyed by prefix. If omitted, the plugin attempts to load available @iconify-json/ packages.
• collectionNamesAlias: An object to customize the name of the collection used in the generated class (e.g., mapping a prefix to a more readable name).
• prefix: The CSS class prefix for matching icon rules. Defaults to i.
• scale: The icon scale. Defaults to 1.
• strokeWidth: The stroke width for the icon.
• extraProperties: Additional CSS properties to apply to the icon component.

The iconsPlugin accepts the following configuration options:

The generateComponent function is a convenience wrapper that takes an icon name and its parent IconifyJSON collection to produce CSS rules.

Parameters:

• name: The specific icon name within the collection (e.g., 'home').
• icons: The IconifyJSON object representing the collection.
• options: A GenerateOptions object (see generateIconComponent for details).

Returns: Returns an object of CSS rules if the icon is found, or null if the icon does not exist in the provided collection.

import { generateComponent } from '@egoist/tailwindcss-icons';

const iconRules = generateComponent({
  name: 'mdi:home',
  icons: myIconifyJsonCollection
}, {
  scale: 1
});

if (iconRules) {
  // Use the rules
}

The iconsPlugin function creates a Tailwind CSS plugin that generates static CSS classes for icons from Iconify collections. It scans provided collections and creates utility classes in the format [collectionName]-[iconName].

By default, it attempts to automatically detect and load available @iconify-json/ packages. You can customize the scale, stroke width, and extra properties applied to the generated icon components.

import iconsPlugin from '@egoist/tailwindcss-icons'

export default {
  plugins: [
    iconsPlugin({
      scale: 1.5,
      strokeWidth: 2,
      prefix: 'icon',
      // collections: { ... } // Optional: provide specific Iconify JSON data
    })
  ]
}

The dynamicIconsPlugin function creates a Tailwind CSS plugin that generates CSS rules dynamically at runtime based on the values passed to the utility class. This is useful when you don't want to pre-generate every possible icon class.

Note that dynamicIconsPlugin does not accept collections or collectionNamesAlias options, as it relies on the value passed to the class to determine the icon content.

import dynamicIconsPlugin from '@egoist/tailwindcss-icons'

export default {
  plugins: [
    dynamicIconsPlugin({
      prefix: 'dyn',
      scale: 1,
      strokeWidth: 2
    })
  ]
}