🌀 A simple tailwindcss plugin to ease work with Google's Material Symbols icons.
See live demo on how the plugin works.
Install the plugin using npm
npm i -D @savaryna/tailwindcss-material-symbolsor pnpm, etc.
pnpm add -D @savaryna/tailwindcss-material-symbolsAdd the plugin to your tailwind.config.js file.
/** @type {import('tailwindcss').Config} */
module.exports = {
theme: {
// ...
},
plugins: [
require('@savaryna/tailwindcss-material-symbols'),
// ...
],
};Follow Google's guide on how to add Material Symbols to your page. For example you could just add a link tag to your pages head.
<head>
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,[email protected],100..700,0..1,-50..200&family=Material+Symbols+Rounded:opsz,wght,FILL,[email protected],100..700,0..1,-50..200&family=Material+Symbols+Sharp:opsz,wght,FILL,[email protected],100..700,0..1,-50..200"
/>
</head>Now you can use the base class icon to style elements as Material Symbols.
Tip
The base class can be changed by passing a baseClass option to the plugin. In that case use your custom base class instead of icon. See changing the default base class for more information.
<span class="icon">star</span>The plugin includes a modifier class for each Material Symbols font family, so you can easily choose what symbol style to use.
Important
All modifier classes need to be used together with the base class. Always include the base class when using a modifier class.
<span class="icon icon-rounded">star</span>
<!-- `icon` is the base class, and -->
<!-- `icon-rounded` is the modifier class -->Here you can see how the base class icon was used together with the icon-rounded modifier which sets the font family to the Rounded variant.
Classes you can use with the default config:
| Class | Font family |
|---|---|
icon-outlined (default) |
'Material Symbols Outlined' |
icon-rounded |
'Material Symbols Rounded' |
icon-sharp |
'Material Symbols Sharp' |
Weight modifiers allow you to adjust the weight of the symbols stroke. Read more here.
<span class="icon icon-700">star</span>Classes you can use with the default config:
| Class | Font weight |
|---|---|
icon-100 |
100 |
icon-200 |
200 |
icon-300 |
300 |
icon-400 (default) |
400 |
icon-500 |
500 |
icon-600 |
600 |
icon-700 |
700 |
These can be animated using transitions.
<span class="icon transition-all hover:icon-700">star</span>Fill modifiers allow you to choose if your symbol is filled or not. Read more here.
Classes you can use with the default config:
| Class | Font fill |
|---|---|
icon-nofill (default) |
0 |
icon-filled |
1 |
These can be animated using transitions.
<label>
<input type="checkbox" class="peer hidden" />
<span class="peer:checked:icon-filled icon transition-all">star</span>
</label>Grade modifiers allow you to choose the weight of the symbols in a more granular way. A lower value is recommended to be used on darker backgrounds. Read more here.
Classes you can use with the default config:
| Class | Font grade |
|---|---|
icon-dark |
-25 |
icon-normal (default) |
0 |
icon-emphasis |
200 |
These can be animated using transitions.
Optical size modifiers allow you to choose the size of the symbols. In addition to changing the symbol size this also changes the stroke weight as the symbol scales. Read more here.
Classes you can use with the default config:
| Class | Font optical size |
|---|---|
icon-20 |
20 |
icon-24 (default) |
24 |
icon-40 |
40 |
icon-48 |
48 |
These can be animated using transitions.
You can use the plugin with Tailwind CSS pseudo elements to add icons using css content.
<label
className="after:icon after:content-['arrow\_drop\_down'] after:absolute after:right-2 ..."
>
<select className="...">
...
</select>
</label>You can use Tailwind CSS classes to animate the font properties. You can animate the weight, fill, grade, optical size and other element features. Read more about using transitions and animations in the tailwindcss documentation. You can also find more information on Google's developer guide for Material Symbols.
| Here are a few examples: |
|---|
transition-all icon group-hover:icon-700 |
transition-all icon group-hover:icon-filled |
transition-all icon group-hover:icon-emphasis |
If you want to use a base class other than icon, you can do so using the baseClass option when registering the plugin:
/** @type {import('tailwindcss').Config} */
module.exports = {
theme: {
// ...
},
plugins: [
require('@savaryna/tailwindcss-material-symbols')({
baseClass: 'symbol',
}),
]
...
}Now you can use your custom symbol base class where you'd use the default base class:
<span class="symbol symbol-rounded">star</span>If you want to customize what modifier classes and values get generated, or change the DEFAULT's you can also extend or override the materialSymbols key in your theme config.
/** @type {import('tailwindcss').Config} */
module.exports = {
theme: {
materialSymbols: {
weight: {
DEFAULT: '700',
},
opticalSize: {
sm: '20',
},
...
}
},
plugins: [
require('@savaryna/tailwindcss-material-symbols'),
]
...
}