phosphor-icons-tailwindcss

phosphor-icons-tailwindcss

A TailwindCSS plugin for the Phosphor icon set.

Installation

1. install package:

   pnpm add -D phosphor-icons-tailwindcss # or via npm, yarn, ...
   

2. register the plugin in your tailwind.config.js:

   // tailwind.config.js
   import phosphorIcons from "phosphor-icons-tailwindcss";
   
   /** @type {import("tailwindcss").Config } */
   export default {
   	plugins: [phosphorIcons()],
   };
   

   Or if you are using Tailwind 4:

   /* app.css, or whatever your entry CSS is */
   @import 'tailwindcss';
   @plugin 'phosphor-icons-tailwindcss';
   

[!IMPORTANT] This package only supports ESM. It should work well in most projects today, especially those using Vite.

Usage

You need to add two classes to your markup:

1. the base ph class,
2. a class with the syntax: ph-[<name><--weight>], corresponding to your desired icon.

[!NOTE] weight is optional and defaults to "regular" if not specified.

For example:

<p>
	<span class="ph ph-[info] text-xl"></span> <!-- render the regular info icon -->
	<i class="ph ph-[pulse--duotone] text-red-500"></i> <!-- render the pulse icon in duotone weight -->
</p>

<div class="ph ph-[file-css] h-6 w-6"></div>

For all available icon names and weight, visit phosphoricons.com.

The output CSS look something like this:

.ph {
	--ph-url: none;
	width: 1em;
	height: 1em;
	background-color: currentcolor;
	color: inherit;
	mask-image: var(--ph-url);
	mask-size: 100% 100%;
	mask-repeat: no-repeat;
}

.ph-\[info\] {
	url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNTYgMjU2IiBmaWxsPSJjdXJyZW50Q29sb3IiPjxwYXRoIGQ9Ik0xMjgsMjRBMTA0LDEwNCwwLDEsMCwyMzIsMTI4LDEwNC4xMSwxMDQuMTEsMCwwLDAsMTI4LDI0Wm0wLDE5MmE4OCw4OCwwLDEsMSw4OC04OEE4OC4xLDg4LjEsMCwwLDEsMTI4LDIxNlptMTYtNDBhOCw4LDAsMCwxLTgsOCwxNiwxNiwwLDAsMS0xNi0xNlYxMjhhOCw4LDAsMCwxLDAtMTYsMTYsMTYsMCwwLDEsMTYsMTZ2NDBBOCw4LDAsMCwxLDE0NCwxNzZaTTExMiw4NGExMiwxMiwwLDEsMSwxMiwxMkExMiwxMiwwLDAsMSwxMTIsODRaIi8+PC9zdmc+);
}

/* ...truncated... */

Configuration

You may pass a configuration object to the plugin to customize the generated CSS. The following shows the default configuration:

// tailwind.config.js
import phosphorIcons from "phosphor-icons-tailwindcss";

/** @type {import("tailwindcss").Config } */
export default {
	plugins: [phosphorIcons({
		prefix: 'ph', // for the icon classes
		customProperty: '--ph-url',
	})],
};

Similarly, for Tailwind 4:

@import 'tailwindcss';
@plugin 'phosphor-icons-tailwindcss' {
	prefix: ph;
	custom-property: --ph-url; /* use the kebab-case alias to avoid auto-format by stylelint / prettier */
}

Why ph-[info] and not ph-info?

You may notice this library utilizes Tailwind's support for arbitrary value, i.e ph-[info] instead of ph-info to map to the regular info icon. This is to avoid unnecessary parsing during development, especially for Taliwind language server. Arbitrary value syntax allows parsing ad-hoc only the icons actually being used. Otherwise, parsing 9000+ icons may cause slow-down that negatively impacts developer experience.

Acknowledgements

You may find @iconify/tailwindcss helpful if you are already using the iconify ecosystem in your codebase.

phosphor-icons-tailwindcss tries to stay minimal by only covering Phosphor icons, and it references directly @phosphor-icons/core for the SVG assets.

Changelog

1.0.3

Patch Changes

• 9b18ea8 Thanks @vnphanquang! - allow passing custom-property option (alias to customProperty) to better match CSS naming convention (helpful to avoid auto-format when used with Tailwind 4 @plugin syntax)