@savaryna/tailwindcss-material-symbols
v1.0.3
Published
🌀 A simple tailwindcss plugin to ease work with Google's Material Symbols font.
Downloads
545
Maintainers
savarynaReadme
@savaryna/tailwindcss-material-symbols
🌀 A simple tailwindcss plugin to ease work with Google's Material Symbols icons.
Live demo
See live demo on how the plugin works.
Installation
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>Basic usage
Now you can use the base class icon to style elements as Material Symbols.
[!TIP] The base class can be changed by passing a
baseClassoption to the plugin. In that case use your custom base class instead oficon. See changing the default base class for more information.
<span class="icon">star</span>Choosing the font
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' |
Choosing the weight
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>Choosing the fill
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>Choosing the grade
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.
Choosing the optical size
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.
With pseudo elements
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>Animating font properties
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 |
Customizing the plugin
Changing the default base class
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>Changing the default styles and classes
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'),
]
...
}