Material Symbols (marella/material-symbols)

Material Symbols

https://github.com/marella/material-symbols
Admin
Material Symbols is a monorepo providing variable icon fonts and optimized SVGs for Material...

Tokens:14,937
Snippets:212
Trust Score:8.2
Update:3 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# 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
<!DOCTYPE html>
<html>
<head>
  <!-- Import all icon styles -->
  <link href="/path/to/node_modules/material-symbols/index.css" rel="stylesheet">

  <!-- Or import specific style only -->
  <link href="/path/to/node_modules/material-symbols/outlined.css" rel="stylesheet">

  <!-- For specific weight packages -->
  <link href="/path/to/node_modules/@material-symbols/font-400/index.css" rel="stylesheet">
</head>
<body>
  <span class="material-symbols-outlined">home</span>
</body>
</html>
```

## Displaying Icons

Use span elements with the appropriate class name to render icons. The icon name goes inside the element as text content.

```html
<!-- Outlined style (default) -->
<span class="material-symbols-outlined">face</span>
<span class="material-symbols-outlined">home</span>
<span class="material-symbols-outlined">settings</span>
<span class="material-symbols-outlined">search</span>
<span class="material-symbols-outlined">favorite</span>

<!-- Rounded style -->
<span class="material-symbols-rounded">face</span>
<span class="material-symbols-rounded">home</span>
<span class="material-symbols-rounded">settings</span>

<!-- Sharp style -->
<span class="material-symbols-sharp">face</span>
<span class="material-symbols-sharp">home</span>
<span class="material-symbols-sharp">settings</span>
```

## 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
<!-- Import in styles.scss first -->
<!-- @import 'material-symbols'; -->

<!-- Use with mat-icon component -->
<mat-icon fontSet="material-symbols-outlined">face</mat-icon>
<mat-icon fontSet="material-symbols-outlined">home</mat-icon>
<mat-icon fontSet="material-symbols-outlined">settings</mat-icon>

<mat-icon fontSet="material-symbols-rounded">face</mat-icon>
<mat-icon fontSet="material-symbols-rounded">home</mat-icon>

<mat-icon fontSet="material-symbols-sharp">face</mat-icon>
<mat-icon fontSet="material-symbols-sharp">home</mat-icon>

<!-- With custom styling -->
<mat-icon fontSet="material-symbols-outlined" class="filled">favorite</mat-icon>
```

## 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 (
    <div className="App">
      <Face />
      <Home />
      <Settings />
      <FavoriteFilled />
    </div>
  );
}

// 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 (
    <div className="App">
      <Face className="icon" />
      <Home className="icon" />
    </div>
  );
}

export default App;
```

## Using SVGs in Vue

Import SVG icons as Vue components using @svgv/webpack for seamless integration in Vue applications.

```vue
<template>
  <div class="App">
    <Face class="icon" />
    <Home class="icon" />
    <Settings class="icon" />
    <!-- Filled variant -->
    <FavoriteFilled class="icon active" />
  </div>
</template>

<script>
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';
import FavoriteFilled from '@material-symbols/svg-400/outlined/favorite-fill.svg';

export default {
  components: {
    Face,
    Home,
    Settings,
    FavoriteFilled,
  },
};
</script>

<style>
.icon {
  width: 24px;
  height: 24px;
  fill: currentColor;
}

.icon.active {
  fill: #e91e63;
}
</style>
```

## 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 <span className={className}>{name}</span>;
}

// Usage
<Icon name="favorite" filled size="large" />
<Icon name="home" />
<Icon name="settings" size="small" />

// 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
<!-- Three icon styles available -->

<!-- Outlined: Default style with outlined strokes -->
<span class="material-symbols-outlined">edit</span>
<!-- CSS class: .material-symbols-outlined -->
<!-- Font family: Material Symbols Outlined -->

<!-- Rounded: Softer appearance with rounded corners -->
<span class="material-symbols-rounded">edit</span>
<!-- CSS class: .material-symbols-rounded -->
<!-- Font family: Material Symbols Rounded -->

<!-- Sharp: Angular appearance with sharp corners -->
<span class="material-symbols-sharp">edit</span>
<!-- CSS class: .material-symbols-sharp -->
<!-- Font family: Material Symbols Sharp -->

<!-- Each style supports the same variable font axes:
     FILL: 0 (outlined) to 1 (filled)
     wght: 100 to 700 (font weight)
     GRAD: -25 to 200 (grade/emphasis)
     opsz: 20 to 48 (optical size)
-->
```

## 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.