# Material Symbols
Material Symbols is a comprehensive monorepo providing the latest variable icon fonts and optimized SVGs for Google's Material Symbols icon library. The package offers icons in three visual styles (Outlined, Rounded, and Sharp) with support for variable font axes including fill, weight, grade, and optical size. All packages are automatically updated via GitHub Actions, ensuring developers always have access to the most current icons from Google.
The library is available as multiple npm packages to suit different project needs: the main `material-symbols` package includes full variable fonts with all weight variations (100-700), while individual `@material-symbols/font-{weight}` packages offer smaller file sizes for projects requiring only specific weights. SVG packages (`@material-symbols/svg-{weight}`) provide optimized vector graphics for both filled and unfilled icon states, ideal for React, Vue, and other component-based frameworks.
## Installation
Install the Material Symbols icon fonts via npm to access over 3,800 icons in your web projects with full variable font support.
```bash
# Install full variable font package (supports weights 100-700)
npm install material-symbols@latest
# Or install a specific weight for smaller bundle size
npm install @material-symbols/font-400@latest
# Install SVG package for component-based usage
npm install @material-symbols/svg-400@latest
```
## Importing in JavaScript
Import the icon fonts directly in your JavaScript entry point file. This approach works with bundlers like webpack, Vite, and build tools in React, Vue, and Angular projects.
```javascript
// Import all icon styles (outlined, rounded, sharp) with full variable font support
import 'material-symbols';
// Or import only the outlined style to reduce bundle size
import 'material-symbols/outlined.css';
// For specific weight packages
import '@material-symbols/font-400';
import '@material-symbols/font-400/outlined.css';
```
## Importing in CSS
Import the icon fonts directly in your CSS or preprocessor files for projects that don't use JavaScript bundlers or prefer CSS-based imports.
```css
/* Import all icon styles */
@import 'material-symbols';
/* Import specific style only */
@import 'material-symbols/outlined.css';
@import 'material-symbols/rounded.css';
@import 'material-symbols/sharp.css';
/* For specific weight packages */
@import '@material-symbols/font-400';
@import '@material-symbols/font-400/outlined.css';
```
## Importing in HTML
Link the CSS files directly in your HTML for static websites or projects without a build process.
```html
home
```
## Displaying Icons
Use span elements with the appropriate class name to render icons. The icon name goes inside the element as text content.
```html
facehomesettingssearchfavoritefacehomesettingsfacehomesettings
```
## Customizing Variable Font Axes
Material Symbols are variable fonts supporting four axes: FILL (0-1), weight (wght: 100-700), grade (GRAD: -25 to 200), and optical size (opsz: 20-48). Customize these via CSS font-variation-settings.
```css
/* Default settings */
.material-symbols-outlined {
font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 48;
}
/* Filled icons */
.material-symbols-outlined.filled {
font-variation-settings: 'FILL' 1, 'wght' 400, 'GRAD' 0, 'opsz' 48;
}
/* Bold icons */
.material-symbols-outlined.bold {
font-variation-settings: 'FILL' 0, 'wght' 700, 'GRAD' 0, 'opsz' 48;
}
/* Light icons */
.material-symbols-outlined.light {
font-variation-settings: 'FILL' 0, 'wght' 200, 'GRAD' 0, 'opsz' 48;
}
/* Custom icon sizes using optical size */
.material-symbols-outlined.small {
font-size: 20px;
font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 20;
}
.material-symbols-outlined.large {
font-size: 48px;
font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 48;
}
/* Emphasized icons with higher grade */
.material-symbols-outlined.emphasized {
font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 200, 'opsz' 48;
}
```
## Using with Sass
Import the Sass files for more control over icon styling and to leverage Sass variables for customizing the font path.
```scss
// Default import
@import 'material-symbols';
// Import specific styles
@import 'material-symbols/outlined';
@import 'material-symbols/rounded';
@import 'material-symbols/sharp';
// If using webpack or Vue CLI, set the font path first
$material-symbols-font-path: '~material-symbols/';
@import 'material-symbols';
// For specific weight packages
$material-symbols-font-path: '~@material-symbols/font-400/';
@import '@material-symbols/font-400';
// Custom icon styling with Sass
.icon-button {
.material-symbols-outlined {
font-size: 24px;
vertical-align: middle;
font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24;
&:hover {
font-variation-settings: 'FILL' 1, 'wght' 400, 'GRAD' 0, 'opsz' 24;
}
}
}
```
## Using with Angular mat-icon
Integrate Material Symbols with Angular Material's mat-icon component by specifying the fontSet attribute.
```html
facehomesettingsfacehomefacehomefavorite
```
## Using SVGs in React
Import SVG icons as React components using @svgr/webpack for optimal bundle size and component-based icon usage.
```jsx
// With @svgr/webpack configured
import Face from '@material-symbols/svg-400/outlined/face.svg';
import Home from '@material-symbols/svg-400/outlined/home.svg';
import Settings from '@material-symbols/svg-400/rounded/settings.svg';
// Filled variants have '-fill' suffix
import FavoriteFilled from '@material-symbols/svg-400/outlined/favorite-fill.svg';
function App() {
return (
);
}
// With Create React App (file-loader + @svgr/webpack)
import { ReactComponent as Face } from '@material-symbols/svg-400/outlined/face.svg';
import { ReactComponent as Home } from '@material-symbols/svg-400/outlined/home.svg';
function App() {
return (
);
}
export default App;
```
## Using SVGs in Vue
Import SVG icons as Vue components using @svgv/webpack for seamless integration in Vue applications.
```vue
```
## SVG File Structure
SVG icons are organized by style directory with unfilled and filled variants. Understanding this structure helps locate the exact icon file you need.
```
@material-symbols/svg-400/
├── outlined/
│ ├── face.svg # Unfilled (FILL 0)
│ ├── face-fill.svg # Filled (FILL 1)
│ ├── home.svg
│ ├── home-fill.svg
│ ├── settings.svg
│ └── settings-fill.svg
├── rounded/
│ ├── face.svg
│ ├── face-fill.svg
│ └── ...
└── sharp/
├── face.svg
├── face-fill.svg
└── ...
# Different weight packages follow the same structure
@material-symbols/svg-100/ # Thin weight
@material-symbols/svg-200/ # Extra Light
@material-symbols/svg-300/ # Light
@material-symbols/svg-400/ # Regular
@material-symbols/svg-500/ # Medium
@material-symbols/svg-600/ # Semi Bold
@material-symbols/svg-700/ # Bold
```
## Styling SVG Icons
Apply CSS styles to SVG icons for consistent sizing and theming. Setting width/height to 1em allows scaling with font-size.
```css
/* Basic SVG icon styling */
.App svg {
width: 1em;
height: 1em;
fill: currentColor;
}
/* Sized icon variants */
.icon-small {
font-size: 16px;
}
.icon-medium {
font-size: 24px;
}
.icon-large {
font-size: 48px;
}
/* Colored icons */
.icon-primary {
color: #1976d2;
}
.icon-secondary {
color: #9c27b0;
}
.icon-error {
color: #d32f2f;
}
/* Icon button styling */
.icon-button {
display: inline-flex;
align-items: center;
justify-content: center;
padding: 8px;
border: none;
background: transparent;
cursor: pointer;
border-radius: 50%;
transition: background-color 0.2s;
}
.icon-button:hover {
background-color: rgba(0, 0, 0, 0.04);
}
.icon-button svg {
width: 24px;
height: 24px;
fill: currentColor;
}
```
## TypeScript Support
The package includes TypeScript type definitions for autocomplete and type checking of icon names.
```typescript
import type { MaterialSymbol } from 'material-symbols';
// Type-safe icon names
const iconName: MaterialSymbol = 'face';
const homeIcon: MaterialSymbol = 'home';
const settingsIcon: MaterialSymbol = 'settings';
// Use in React component props
interface IconProps {
name: MaterialSymbol;
filled?: boolean;
size?: 'small' | 'medium' | 'large';
}
function Icon({ name, filled = false, size = 'medium' }: IconProps) {
const className = `material-symbols-outlined ${filled ? 'filled' : ''} ${size}`;
return {name};
}
// Usage
// TypeScript will error on invalid icon names
// const invalid: MaterialSymbol = 'invalid-icon'; // Error!
```
## Available Icon Styles Summary
Reference table showing all available CSS classes and their corresponding visual styles.
```html
editeditedit
```
## Summary
Material Symbols provides a flexible and comprehensive icon solution for modern web development. The main use cases include using the full variable font package for applications requiring dynamic icon weight and fill adjustments, using weight-specific font packages for optimized bundle sizes in production, and using SVG packages for component-based frameworks like React and Vue where icons need to be imported as components. The library supports all major frameworks including React, Vue, Angular, and vanilla HTML/CSS projects.
Integration patterns vary by project type: JavaScript-bundled projects should import via ES modules in their entry files, Sass/SCSS projects can leverage the provided Sass files with customizable font paths, and static HTML projects can link the CSS files directly. For TypeScript projects, the included type definitions enable autocomplete and type safety for icon names. The automatic update system via GitHub Actions ensures the packages always include the latest icons from Google's Material Symbols library.