@spencerwmiles/tailwind-material-symbols v0.1.2
Tailwind Material Symbols
Tailwind CSS v4 utilities for Google's Material Symbols variable font. Compatible with tailwind-merge.
This package brings Google's Material Symbols design system to Tailwind CSS, built on top of the excellent material-symbols package by @marella. The material-symbols package provides the latest variable icon fonts and optimized SVGs, automatically updating from Google's official releases to ensure you always have access to the newest icons.
Installation
npm install @spencerwmiles/tailwind-material-symbols
This package automatically includes two core dependencies:
@spencerwmiles/tailwind-font-variations
- Provides variable font utilitiesmaterial-symbols
- Provides the actual Material Symbols font files
Setup
Full Package (All Variants)
Import in your main CSS file to get all three font variants:
@import '@spencerwmiles/tailwind-material-symbols';
Specific Variants (Smaller Bundle Size)
For better performance, import only the variant you need:
/* Outlined only (most common) */
@import '@spencerwmiles/tailwind-material-symbols/outlined.css';
/* Rounded only */
@import '@spencerwmiles/tailwind-material-symbols/rounded.css';
/* Sharp only */
@import '@spencerwmiles/tailwind-material-symbols/sharp.css';
Recommendation: Use specific imports in production to minimize bundle size. The outlined variant is the most commonly used.
How It Works
This package uses a composition approach with three core packages:
- This package (
tailwind-material-symbols
): Provides Material Symbols font families and the FILL axis - Font variations package (
tailwind-font-variations
): Provides weight, grade, and optical size utilities - Material Symbols package (
material-symbols
): Provides the actual font files from Google
You combine utilities from these packages to create the exact symbol styling you need.
Usage
Basic Symbols
<span class="symbol">home</span>
<span class="symbol">favorite</span>
<span class="symbol">settings</span>
Font Variants
When using the full package import, you can switch between variants:
<span class="symbol symbol-outlined">favorite</span>
<span class="symbol symbol-rounded">favorite</span>
<span class="symbol symbol-sharp">favorite</span>
When using specific variant imports, the font is already set:
<!-- With outlined.css import -->
<span class="symbol">favorite</span>
<!-- With rounded.css import -->
<span class="symbol">favorite</span>
<!-- With sharp.css import -->
<span class="symbol">favorite</span>
Fill States (Material Symbols Specific)
<!-- Filled (default) -->
<span class="symbol">star</span>
<!-- Outlined -->
<span class="symbol symbol-fill-0">star</span>
<!-- Explicitly filled -->
<span class="symbol symbol-fill-1">star</span>
<!-- Partially filled -->
<span class="symbol symbol-fill-[0.5]">star</span>
Variable Font Axes (From font-variations package)
<!-- Weight -->
<span class="symbol variation-setting-wght-700">settings</span>
<!-- Grade (emphasis) -->
<span class="symbol variation-setting-GRAD-100">home</span>
<!-- Optical size -->
<span class="symbol variation-setting-opsz-48">close</span>
<!-- Negative values -->
<span class="symbol variation-setting-GRAD--25">home</span>
Combining Everything
<!-- Rounded, filled, bold, high grade -->
<span class="symbol symbol-rounded symbol-fill-1 variation-setting-wght-700 variation-setting-GRAD-100">
star
</span>
<!-- Sharp, outlined, light weight, optimized for large size -->
<span class="symbol symbol-sharp variation-setting-wght-300 variation-setting-opsz-48">
home
</span>
Responsive Design
<span class="symbol symbol-fill-0 md:symbol-fill-1 variation-setting-wght-400 md:variation-setting-wght-700">
favorite
</span>
Transitions
<!-- Smooth fill transition -->
<span class="symbol symbol-fill-0 transition-font-variations duration-300 hover:symbol-fill-1">
favorite
</span>
<!-- Multiple property transitions -->
<span class="symbol symbol-fill-0 transition-font-variations duration-200 hover:symbol-fill-1 hover:variation-setting-wght-700">
star
</span>
With Tailwind Utilities
<!-- Size with text utilities -->
<span class="symbol text-2xl text-blue-500">home</span>
<!-- With spacing and colors -->
<span class="symbol symbol-fill-1 variation-setting-wght-600 text-red-500 mr-2">
error
</span>
Customizing Defaults
Override default symbol behavior using Tailwind v4's @theme
directive. This works reliably across all import methods:
When Using Full Package (all.css
)
@import '@spencerwmiles/tailwind-material-symbols';
@theme {
/* Change default fill (0 = outlined, 1 = filled) */
--symbol-fill-default: var(--symbol-fill-0);
/* Change default font variant (applies to base symbol utility) */
--font-family-material-symbols-default: 'Material Symbols Rounded';
}
With this setup:
<span class="symbol">home</span>
→ Uses Rounded variant (your new default)<span class="symbol symbol-outlined">home</span>
→ Forces Outlined variant<span class="symbol symbol-sharp">home</span>
→ Forces Sharp variant
When Using Specific Variants
@import '@spencerwmiles/tailwind-material-symbols/rounded.css';
@theme {
/* Only fill customization is relevant for specific imports */
--symbol-fill-default: var(--symbol-fill-0);
}
Available Default Variables
@theme {
/* Fill defaults */
--symbol-fill-default: var(--symbol-fill-1); /* 1 = filled, 0 = outlined */
/* Font family defaults (all.css only) */
--font-family-material-symbols-default: 'Material Symbols Outlined'; /* or Rounded/Sharp */
/* Individual variant references (available in all imports) */
--font-family-material-symbols-outlined: 'Material Symbols Outlined';
--font-family-material-symbols-rounded: 'Material Symbols Rounded';
--font-family-material-symbols-sharp: 'Material Symbols Sharp';
}
Import Options
Full Package (@import '@spencerwmiles/tailwind-material-symbols'
)
- Includes: All three font variants (Outlined, Rounded, Sharp)
- Size: Larger bundle (~3 font files)
- Use case: When you need multiple variants or want maximum flexibility
- Utilities:
symbol-outlined
,symbol-rounded
,symbol-sharp
for switching variants
Specific Variants (@import '@spencerwmiles/tailwind-material-symbols/outlined.css'
)
- Includes: Only the specified variant
- Size: Smaller bundle (~1 font file)
- Use case: Production apps where you know which variant you need
- Utilities: No variant switching utilities (font is pre-set)
Package Responsibilities
This Package Provides:
symbol
- Base Material Symbols component (filled by default)symbol-outlined/rounded/sharp
- Font family variants (full package only)symbol-fill-1
- Filled state (explicit)symbol-fill-0
- Outlined statesymbol-fill-[value]
- Custom fill values (0-1)
Font Variations Package Provides:
variation-setting-wght-*
- Weight axis (100-900)variation-setting-GRAD-*
- Grade axis (-200 to 300)variation-setting-opsz-*
- Optical size axis (8-144)transition-font-variations
- Transition utility- Plus support for any custom variable font axes
Why This Approach?
This composition pattern provides several benefits:
- No Redundancy: Each package handles what it does best
- Maximum Flexibility: Combine utilities exactly as needed
- Tailwind Philosophy: Composable building blocks, not opinionated combinations
- Future Proof: Easy to extend with new axes or fonts
- Bundle Efficiency: Only includes utilities you actually use
Material Symbols Reference
For available symbols, visit the Material Symbols Library.
License
MIT License - see LICENSE for details.