@jcamp/tailwindcss-plugin-icons
v0.6.2TypeScript
Automatic icon creator for Tailwind
0/weekUpdated 2 years agoMITUnpacked: 34.0 KB
Published by John Campion
npm install @jcamp/tailwindcss-plugin-icons@jcamp/tailwindcss-plugin-icons
Tailwind CSS Icons Plugin
Automatic icon creator for Tailwind CSS
Use any icons with Pure CSS for TailwindCSS.
Recommended reading - @antfu's post titled Icons in Pure CSS.
Follow the following conventions to use the icons
-
- i-[ - default prefix is i-
For examples:
``html`
/>
This is powered by pure CSS
Install
`bash`
npm i -D @jcamp/tailwindcss-plugin-icons @iconify-json/[the-collection-you-want]
We use Iconify as our data source of icons. You need to install the corresponding iconset in devDependencies by following the @iconify-json/* pattern. For example, @iconify-json/mdi for Material Design Icons, @iconify-json/tabler for Tabler. You can refer to Icônes or Iconify for all the collections available.
Then add the plugin to your tailwind.config.js file:
`js
// tailwind.config.js
const icons = require('@jcamp/tailwindcss-plugin-icons')
module.exports = {
theme: {
// ...
},
plugins: [
icons({
/ options /
}),
// ...
],
}
`
`ts
// tailwind.config.ts
import type { Config } from 'tailwindcss'
import iconsPlugin from '@jcamp/tailwindcss-plugin-icons'
export default
theme: {
// ...
},
plugins: [
iconsPlugin({
/ options /
}),
],
}
`
If you prefer to install the all the icon sets available on Iconify at once (~130MB):
`bash`
npm i -D @iconify/json
Class names
The structure is i-[
The collection and name can be divided by either a dash - or a slash /. Unfortunately, Tailwind CSS will not pass a colon : properly to the plugin.
If you want to add scaling to the class, you must separate that with a slash /. You can add the unit (px|em|rem) but it is optional. If omitted, it will use the default specified by the config.
`html`
JSON collections
As a big fan of Font Awesome, I wanted this to work with their pro collections. It now does. There is a new jsonCollections property in the config that allows you to tell the plugin where to load JSON files from.
`js`
jsonCollections: {
custom: 'json/custom-collection.json',
},
Configuration
Refer to the type definition for all configurations avaliable.
$3
You can provide the extra CSS properties to control the default behavior of the icons. The following is an example of make icons inlined by default:
`ts`
presetIcons({
extraProperties: {
display: 'inline-block',
'vertical-align': 'middle',
// ...
},
})
Modes Overriding
By default, this preset will choose the rendering modes automatically for each icon based on the icons' characteristics. You can read more in this blog post. In some cases, you may want to explicitly set the rendering modes for each icon.
- i-bg- for background-img - renders the icon as a background imagei-mask-
- for mask - renders the icon as a mask image
$3
Because Tailwind does not allow async plugins, see https://github.com/tailwindlabs/tailwindcss/discussions/7277, we are using a node process to retrieve the icons, so right now, this will not work in the browser directly.
#### Customization
Although there is code similar to UnoCSS's customizations, I have not yet had time to write tests for it and confirm it works as expected, so this information will not be in the README for now.
$3
In Node.js the preset will search for the installed iconify dataset automatically and so you don't need to register the iconify` collections.
Credits
This plugin is heaviliy inspired by and based on the work of UnoCSS Icons Preset created by Anthony Fu
It is also based on some ideas by InfiniteXyy and their work at tailwindcss-iconify. In particular, their idea for spawning a node process to allow async code to work in Tailwinds sync plugin system.
License
MIT License © 2022-PRESENT John Campion