@spencerwmiles/tailwind-material-symbols

# 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](https://github.com/marella/material-symbols) package by [@marella](https://github.com/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 ```bash npm install @spencerwmiles/tailwind-material-symbols ``` This package automatically includes two core dependencies: - `@spencerwmiles/tailwind-font-variations` - Provides variable font utilities - `material-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: ```css @import '@spencerwmiles/tailwind-material-symbols'; ``` ### Specific Variants (Smaller Bundle Size) For better performance, import only the variant you need: ```css /* 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 ```html home favorite settings ``` ### Font Variants When using the full package import, you can switch between variants: ```html favorite favorite favorite ``` When using specific variant imports, the font is already set: ```html  favorite  favorite  favorite ``` ### Fill States (Material Symbols Specific) ```html  star  star  star  star ``` ### Variable Font Axes (From font-variations package) ```html  settings  home  close  home ``` ### Combining Everything ```html  star  home ``` ### Responsive Design ```html favorite ``` ### Transitions ```html  favorite  star ``` ### With Tailwind Utilities ```html  home  error ``` ## 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`) ```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: - `home` → Uses Rounded variant (your new default) - `home` → Forces Outlined variant - `home` → Forces Sharp variant ### When Using Specific Variants ```css @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 ```css @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 state - `symbol-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: 1. **No Redundancy**: Each package handles what it does best 2. **Maximum Flexibility**: Combine utilities exactly as needed 3. **Tailwind Philosophy**: Composable building blocks, not opinionated combinations 4. **Future Proof**: Easy to extend with new axes or fonts 5. **Bundle Efficiency**: Only includes utilities you actually use ## Material Symbols Reference For available symbols, visit the [Material Symbols Library](https://fonts.google.com/icons?icon.set=Material+Symbols). ## License MIT License - see [LICENSE](./LICENSE) for details.