# Material Symbols & Material Icons — User Guide

This repository (`google/material-design-icons`) is Google's official, source-of-truth distribution of two icon sets: **Material Symbols** (the current set, built on variable-font technology) and **Material Icons** (the classic set, frozen since 2022). Both sets share the same underlying designs and are published here as ready-to-use assets — SVG, PNG, Android vector drawables, iOS asset catalogs, static fonts, and variable fonts.

This guide shows you how to find the exact icon you need, choose the right style and format, and drop it into a web, Android, or iOS project. It covers every directory layout and file-naming convention in the repository so you can navigate roughly five million asset files with confidence.

> [!IMPORTANT]
> For most projects you do **not** need to clone this repository. The fastest way to use these icons is the Google Fonts hosted web font (see [Quick Start](#1-quick-start)). Clone the repo only when you need the raw asset files — individual SVGs, platform-native drawables, or self-hosted font files.

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Which Set Should You Use?](#2-which-set-should-you-use)
3. [Installation & Access](#3-installation--access)
4. [Finding an Icon](#4-finding-an-icon)
5. [Using Icons on the Web](#5-using-icons-on-the-web)
6. [Using Icons on Android](#6-using-icons-on-android)
7. [Using Icons on iOS](#7-using-icons-on-ios)
8. [Styles, Sizes & Design Axes](#8-styles-sizes--design-axes)
9. [Repository Layout Reference](#9-repository-layout-reference)
10. [Common Tasks](#10-common-tasks)
11. [Requesting a New Icon](#11-requesting-a-new-icon)
12. [Troubleshooting](#12-troubleshooting)
13. [FAQ](#13-faq)
14. [Reference Tables](#14-reference-tables)

---

## 1. Quick Start

The quickest way to use a Material icon is to link the hosted web font from Google Fonts and reference an icon by its name.

=== "Material Symbols (current)"

    ```html
    <!-- 1. Load the font in your page <head> -->
    <link rel="stylesheet"
          href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined">

    <!-- 2. Render an icon by name -->
    <span class="material-symbols-outlined">home</span>
    ```

=== "Material Icons (classic)"

    ```html
    <!-- 1. Load the font in your page <head> -->
    <link rel="stylesheet"
          href="https://fonts.googleapis.com/css2?family=Material+Icons">

    <!-- 2. Render an icon by name -->
    <span class="material-icons">home</span>
    ```

The text inside the `<span>` (`home`) is the **icon name** — the same name used throughout this repository's folder structure. The font uses ligatures to turn that name into the glyph.

> [!TIP]
> Browse and copy icon names visually at **[fonts.google.com/icons](https://fonts.google.com/icons)**. Use the set selector near the top-left to switch between Material Symbols (default) and Material Icons.

> [!NOTE]
> Expected result: a house icon renders inline at the current font size. If you see the literal word `home` instead of an icon, the font stylesheet has not loaded — see [Troubleshooting](#error-icon-renders-as-the-literal-icon-name-text).

---

## 2. Which Set Should You Use?

There are two distinct icon sets in this repository. Choosing the right one is the most important decision you'll make.

| | **Material Symbols** | **Material Icons** |
|---|---|---|
| Status | **Current** — actively maintained | Classic — **frozen since 2022** |
| Introduced | April 2022 | Original set |
| Technology | Variable font (adjustable axes) | Static fonts + static assets |
| Styles | Outlined, Rounded, Sharp | Filled, Outlined, Round, Sharp, Two-tone |
| Adjustable weight | Yes (100–700) | No (Regular only) |
| Adjustable optical size | Yes (20–48 px) | No |
| Adjustable grade | Yes (−50 to 200) | No |
| Fill animation | Yes (Fill axis 0–1) | No |
| Two-tone style | No | Yes |
| New icons added | Yes | No |
| Repo directories | `symbols/`, `variablefont/` | `android/`, `font/`, `ios/`, `png/`, `src/` |

> [!TIP]
> **Use Material Symbols for new projects.** It is the current set, receives new icons, and gives you weight, optical-size, grade, and fill control from a single font file. Reach for Material Icons only when you specifically need the classic look, a **two-tone** style, or platform-native static assets (PNG/drawable) that the classic set ships and Symbols does not.

> [!NOTE]
> Both sets are designed under the [Material Design guidelines](https://material.io/guidelines/) and share the same core icon concepts, so `home` means the same icon in both.

---

## 3. Installation & Access

There are three ways to get these icons, in increasing order of how much of the repository you need.

### Option A — Hosted web font (recommended)

No installation. Link the stylesheet from Google Fonts as shown in [Quick Start](#1-quick-start). Google serves the font, handles caching, and keeps it current. Best for web projects.

### Option B — Download individual assets

Browse to [fonts.google.com/icons](https://fonts.google.com/icons), select an icon, choose a style and format, and download the single SVG or PNG. Best when you need one or a handful of icons.

### Option C — Clone or sparse-checkout the repository

Use this when you need many raw assets, platform-native files, or self-hosted fonts.

> [!CAUTION]
> A full clone is **very large** — the working tree contains roughly five million files across every icon, style, size, and density. A complete checkout can take many minutes and consume several gigabytes of disk. Use a shallow and/or sparse checkout to take only what you need.

=== "Shallow clone (latest snapshot only)"

    ```bash
    git clone --depth 1 https://github.com/google/material-design-icons.git
    ```

    ```text
    Cloning into 'material-design-icons'...
    remote: Enumerating objects: done.
    Receiving objects: 100% (...), several GB, done.
    Updating files: 100% done.
    ```

=== "Sparse checkout (one set only)"

    ```bash
    git clone --depth 1 --filter=blob:none --sparse \
      https://github.com/google/material-design-icons.git
    cd material-design-icons
    # Take only the current variable fonts:
    git sparse-checkout set variablefont
    ```

=== "Just the font files (no clone)"

    ```bash
    # Classic static fonts:
    curl -LO https://raw.githubusercontent.com/google/material-design-icons/master/font/MaterialIcons-Regular.ttf
    # Current variable font (Symbols Outlined):
    curl -LO "https://raw.githubusercontent.com/google/material-design-icons/master/variablefont/MaterialSymbolsOutlined%5BFILL,GRAD,opsz,wght%5D.ttf"
    ```

> [!TIP]
> If you only want a web font + CSS via a package manager, the community-maintained npm packages `material-symbols` and `material-icons` (by `@marella`) repackage these assets. They are **not** maintained or vetted by Google — see [FAQ](#q-is-there-an-official-npm-package).

---

## 4. Finding an Icon

Every icon lives at a path built from three pieces: **category**, **icon name**, and **style**. Understanding this lets you locate any asset directly.

```text
{distribution}/{category}/{icon_name}/{style}/...
```

For example, the classic SVG for the `home` icon in the `action` category, filled style:

```text
src/action/home/materialicons/24px.svg
```

### Icon categories

Every icon belongs to exactly one of these 18 categories (this is the first path segment under each distribution directory):

| | | | |
|---|---|---|---|
| `action` | `alert` | `av` | `communication` |
| `content` | `device` | `editor` | `file` |
| `hardware` | `home` | `image` | `maps` |
| `navigation` | `notification` | `places` | `search` |
| `social` | `toggle` | | |

> [!NOTE]
> The category is a metadata grouping, not part of the icon's user-facing name. When you use a font, you reference only the icon name (e.g. `home`) — the category never appears. You only need the category to locate the **raw asset files** in the repo.

> [!TIP]
> If you know an icon's name but not its category, the simplest path is to search for it at [fonts.google.com/icons](https://fonts.google.com/icons), or use a recursive directory search in a clone:
> ```bash
> find src -type d -name delete
> ```
> ```text
> src/action/delete
> ```

---

## 5. Using Icons on the Web

The web has the most options: a hosted font, self-hosted fonts, raw SVG, and the variable font with adjustable axes.

### 5.1 Hosted icon font

This is the simplest approach. Load the stylesheet and use a styled element.

=== "Material Symbols"

    ```html
    <link rel="stylesheet"
          href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined">

    <span class="material-symbols-outlined">settings</span>
    <span class="material-symbols-outlined">favorite</span>
    ```

=== "Material Icons"

    ```html
    <link rel="stylesheet"
          href="https://fonts.googleapis.com/css2?family=Material+Icons">

    <span class="material-icons">settings</span>
    <span class="material-icons">favorite</span>
    ```

The browser turns the icon name into a glyph using the font's **ligature** table. Size and color follow normal CSS `font-size` and `color`.

```css
.material-symbols-outlined {
  font-size: 48px;   /* icon is 48px tall */
  color: #1a73e8;    /* icons inherit text color */
}
```

> [!NOTE]
> Each classic style is a separate font family with its own stylesheet URL: `Material+Icons`, `Material+Icons+Outlined`, `Material+Icons+Round`, `Material+Icons+Sharp`, `Material+Icons+Two+Tone`. See the [Reference Tables](#14-reference-tables).

### 5.2 Controlling Material Symbols axes in CSS

The current set is a variable font, so you can adjust four axes with `font-variation-settings`:

```css
.material-symbols-outlined {
  font-variation-settings:
    'FILL' 0,    /* 0 = outline, 1 = filled */
    'wght' 400,  /* weight 100–700 */
    'GRAD' 0,    /* grade -50 to 200 */
    'opsz' 24;   /* optical size 20–48 */
}
```

> [!TIP]
> The **Fill** axis is designed for interaction. Animate `FILL` from `0` to `1` to fill an icon when a user selects it (e.g. a "favorite" star), giving a smooth selected-state effect from a single glyph.

> [!IMPORTANT]
> The Material Icons classic set has **no** adjustable axes. `font-variation-settings` has no effect on it — only the Symbols set responds.

### 5.3 Raw SVG

If you'd rather not load a font, use the standalone SVG files.

- **Classic icons:** `src/{category}/{name}/{style}/24px.svg`
- **Current symbols:** `symbols/web/{name}/{style}/{name}_{variant}_{size}px.svg`

```html
<!-- Classic filled "home" SVG, inlined -->
<img src="src/action/home/materialicons/24px.svg" width="24" height="24" alt="Home">
```

```html
<!-- Current Symbols "home", outlined, 24px -->
<img src="symbols/web/home/materialsymbolsoutlined/home_24px.svg" width="24" height="24" alt="Home">
```

> [!NOTE]
> Classic SVGs are provided at the single design size `24px`. The current Symbols set provides multiple optical sizes — `20px`, `24px`, `40px`, and `48px` — plus fill and grade variants baked into separate files (see [§8](#8-styles-sizes--design-axes)).

### 5.4 Self-hosted variable font

To self-host the current set, take the variable font from `variablefont/` and declare an `@font-face`:

```css
@font-face {
  font-family: 'Material Symbols Outlined';
  font-style: normal;
  src: url('MaterialSymbolsOutlined[FILL,GRAD,opsz,wght].woff2') format('woff2');
}
.material-symbols-outlined {
  font-family: 'Material Symbols Outlined';
  font-weight: normal;
  font-feature-settings: 'liga';  /* enable name-to-glyph ligatures */
}
```

The `variablefont/` directory provides each style as `.woff2` (for the web), `.ttf`, and a `.codepoints` file mapping every icon name to its Unicode codepoint.

---

## 6. Using Icons on Android

The classic Material Icons set ships Android-ready assets; the current Symbols set ships Android vector XML.

### 6.1 Classic icons (vector drawables + PNG)

Classic Android assets live under `android/{category}/{name}/{style}/black/res/`. Each icon provides:

- **Vector drawables** in `res/drawable/` — `baseline_{name}_24.xml` (preferred; scalable, small).
- **Raster PNGs** in `res/drawable-{density}/` for every density bucket: `mdpi`, `hdpi`, `xhdpi`, `xxhdpi`, `xxxhdpi`, at sizes `18`, `20`, `24`, `36`, `48`.

```text
android/action/home/materialicons/black/res/drawable/baseline_home_24.xml
android/action/home/materialicons/black/res/drawable-xxhdpi/baseline_home_black_24.png
```

To use the vector drawable, copy the `.xml` into your project's `res/drawable/` folder and reference it:

```xml
<ImageView
    android:layout_width="24dp"
    android:layout_height="24dp"
    android:src="@drawable/baseline_home_24" />
```

> [!TIP]
> Prefer the vector drawable (`res/drawable/*.xml`) over the PNGs. One vector file scales to every screen density, so you avoid bundling five PNG buckets per icon.

### 6.2 Current symbols (vector XML)

The current set provides Android vector XML at:

```text
symbols/android/{name}/{style}/{name}_{variant}_{size}px.xml
```

For example, the outlined `home` symbol at 24 px:

```text
symbols/android/home/materialsymbolsoutlined/home_24px.xml
```

Variants encode the weight/fill/grade combination in the filename (e.g. `home_fill1_24px.xml`). Copy the variant you need into `res/drawable/` and reference it like any other vector drawable.

> [!NOTE]
> Android Studio's built-in **Vector Asset** tool also bundles a copy of Material Icons. Using these repo files directly is useful when you need a specific style, size, or symbol variant the IDE doesn't expose.

---

## 7. Using Icons on iOS

The classic set ships iOS-native asset catalogs; the current set ships iOS-flavored SVGs.

### 7.1 Classic icons (Xcode asset catalogs)

Classic iOS assets are pre-packaged `.xcassets` image sets with `@1x`, `@2x`, and `@3x` PNGs and a `Contents.json`:

```text
ios/action/home/materialicons/black/baseline_home_black_24pt.xcassets/
  baseline_home_black_24pt.imageset/
    baseline_home_black_24pt_1x.png
    baseline_home_black_24pt_2x.png
    baseline_home_black_24pt_3x.png
    Contents.json
```

Drag the `.xcassets` (or the inner `.imageset`) into your Xcode project's asset catalog, then reference the image by name:

```swift
let homeIcon = UIImage(named: "baseline_home_black_24pt")
```

Sizes are provided at `18pt`, `20pt`, `24pt`, `36pt`, and `48pt`.

### 7.2 Current symbols (SVG)

The current set provides iOS-oriented SVGs at:

```text
symbols/ios/{name}/{style}/{name}_{variant}_symbol.svg
```

For example:

```text
symbols/ios/home/materialsymbolsoutlined/home_symbol.svg
symbols/ios/home/materialsymbolsoutlined/home_fill1_symbol.svg
```

> [!NOTE]
> Unlike the web and Android symbol assets, the iOS symbol SVGs do **not** include weight (`wght`) variants — only fill and grade variations are produced for the iOS path. This is by design in the asset pipeline.

Import the SVG into your project (Xcode 12+ supports SVG image assets), or convert it to a template image and tint it with your app's accent color.

---

## 8. Styles, Sizes & Design Axes

### 8.1 Style families

The **style** is the third path segment (the folder name) and also appears as a filename prefix on classic assets.

| Set | Style | Directory segment | Classic file prefix |
|---|---|---|---|
| Material Icons | Filled (default) | `materialicons` | `baseline_` |
| Material Icons | Outlined | `materialiconsoutlined` | `outline_` |
| Material Icons | Round | `materialiconsround` | `round_` |
| Material Icons | Sharp | `materialiconssharp` | `sharp_` |
| Material Icons | Two-tone | `materialiconstwotone` | `twotone_` |
| Material Symbols | Outlined | `materialsymbolsoutlined` | *(axis-encoded)* |
| Material Symbols | Rounded | `materialsymbolsrounded` | *(axis-encoded)* |
| Material Symbols | Sharp | `materialsymbolssharp` | *(axis-encoded)* |

> [!NOTE]
> The classic "Filled" style is the original Material Icons look — its font family is simply called *Material Icons* and its files use the `baseline_` prefix.

### 8.2 Material Symbols design axes

Each Material Symbols variable font exposes four axes you can vary continuously:

| Axis | Tag | Range | Default | Meaning |
|---|---|---|---|---|
| Optical Size | `opsz` | 20 – 48 px | 24 | Stroke/detail tuned for the rendered size |
| Weight | `wght` | 100 (Thin) – 700 (Bold) | 400 (Regular) | Stroke thickness |
| Grade | `GRAD` | −50 – 200 | 0 | Fine weight adjustment without changing size; use −50 for light-on-dark |
| Fill | `FILL` | 0 – 1 | 0 | 0 = outline, 1 = filled; animatable for selection states |

> [!TIP]
> Use **Grade −50** for white (or light) icons on a dark background. It slightly thins the strokes to compensate for the optical "bloom" that light shapes appear to have on dark surfaces.

> [!IMPORTANT]
> In the **static** symbol asset files (under `symbols/`), these axes are baked into discrete variants encoded in the filename — e.g. `home_24px.svg` (defaults), `home_fill1_24px.svg` (filled), `home_grad200fill1_24px.svg` (grade 200 + filled), `home_gradN25_symbol.svg` (grade −50). Only the **variable font** in `variablefont/` lets you set any value on the continuous range.

### 8.3 Sizes

| Set | Available sizes |
|---|---|
| Classic SVG (`src/`) | `24px` (single design size) |
| Classic PNG (`png/`) | `18dp`, `24dp`, `36dp`, `48dp` × `1x`, `2x`, `3x` |
| Classic Android PNG | sizes `18`, `20`, `24`, `36`, `48` × 5 density buckets |
| Classic iOS | `18pt`, `20pt`, `24pt`, `36pt`, `48pt` × `@1x`/`@2x`/`@3x` |
| Symbols SVG/XML | `20px`, `24px`, `40px`, `48px` |

> [!NOTE]
> Per Google's own note, only the **20 px and 24 px** Material Symbols are designed with perfect pixel-grid alignment. Larger optical sizes are intended for display use.

---

## 9. Repository Layout Reference

The repository's top level contains the two icon sets split across seven asset directories plus a maintenance toolchain.

```text
material-design-icons/
├── src/           Classic Material Icons — source SVGs (24px)
├── png/           Classic Material Icons — raster PNGs (18–48dp, 1x/2x/3x)
├── android/       Classic Material Icons — Android vector drawables + density PNGs
├── ios/           Classic Material Icons — Xcode .xcassets imagesets (1x/2x/3x)
├── font/          Classic Material Icons — static fonts (.otf/.ttf) + .codepoints
├── symbols/       Current Material Symbols — web SVG / android XML / ios SVG
│   ├── web/
│   ├── android/
│   └── ios/
├── variablefont/  Current Material Symbols — variable fonts (.ttf/.woff2) + .codepoints
├── update/        Maintenance toolchain (regenerates this repo — see Admin Guide)
├── README.md
└── LICENSE
```

### Path templates by distribution

| Distribution | Path template |
|---|---|
| Classic SVG | `src/{category}/{name}/{style}/24px.svg` |
| Classic PNG | `png/{category}/{name}/{style}/{size}dp/{scale}/{prefix}_{name}_black_{size}dp.png` |
| Classic Android vector | `android/{category}/{name}/{style}/black/res/drawable/{prefix}_{name}_{size}.xml` |
| Classic Android PNG | `android/{category}/{name}/{style}/black/res/drawable-{density}/{prefix}_{name}_black_{size}.png` |
| Classic iOS | `ios/{category}/{name}/{style}/black/{prefix}_{name}_black_{size}pt.xcassets/...` |
| Classic font | `font/MaterialIcons{Style}-Regular.{otf,ttf}` |
| Symbols web SVG | `symbols/web/{name}/{style}/{name}{_variant}_{size}px.svg` |
| Symbols Android XML | `symbols/android/{name}/{style}/{name}{_variant}_{size}px.xml` |
| Symbols iOS SVG | `symbols/ios/{name}/{style}/{name}{_variant}_symbol.svg` |
| Symbols variable font | `variablefont/MaterialSymbols{Style}[FILL,GRAD,opsz,wght].{ttf,woff2}` |

Where `{style}` is one of the directory segments from [§8.1](#81-style-families), `{prefix}` is the matching classic file prefix, and `{_variant}` is the axis encoding (e.g. `_fill1`, `_grad200fill1`, `_wght700`) or empty for defaults.

### The `font/` and `variablefont/` directories

```text
font/
  MaterialIcons-Regular.ttf            MaterialIcons-Regular.codepoints
  MaterialIconsOutlined-Regular.otf    MaterialIconsOutlined-Regular.codepoints
  MaterialIconsRound-Regular.otf       MaterialIconsRound-Regular.codepoints
  MaterialIconsSharp-Regular.otf       MaterialIconsSharp-Regular.codepoints
  MaterialIconsTwoTone-Regular.otf     MaterialIconsTwoTone-Regular.codepoints

variablefont/
  MaterialSymbolsOutlined[FILL,GRAD,opsz,wght].ttf  + .woff2 + .codepoints
  MaterialSymbolsRounded[FILL,GRAD,opsz,wght].ttf   + .woff2 + .codepoints
  MaterialSymbolsSharp[FILL,GRAD,opsz,wght].ttf     + .woff2 + .codepoints
```

> [!TIP]
> The `.codepoints` files are plain text mapping each icon name to its hex Unicode codepoint (`home e88a`). Use them to look up the raw codepoint if you'd rather render by codepoint (`&#xe88a;`) than by ligature name.

---

## 10. Common Tasks

### Add a single icon to a website (fastest path)

1. Find the icon name at [fonts.google.com/icons](https://fonts.google.com/icons).
2. Add the stylesheet link for your chosen set/style.
3. Drop a styled `<span>` with the icon name.

```html
<link rel="stylesheet"
      href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded">
<span class="material-symbols-rounded">shopping_cart</span>
```

### Self-host icons for an offline or privacy-sensitive app

1. Copy the variable font for your style from `variablefont/` (use the `.woff2` for web).
2. Declare an `@font-face` (see [§5.4](#54-self-hosted-variable-font)).
3. Reference icons by ligature name with `font-feature-settings: 'liga'` enabled.

### Pull a single Android vector drawable

```bash
curl -LO https://raw.githubusercontent.com/google/material-design-icons/master/android/action/home/materialicons/black/res/drawable/baseline_home_24.xml
```

```text
# baseline_home_24.xml — copy into your project's res/drawable/
```

### Make a filled "favorite" toggle on the web

```css
.fav { font-variation-settings: 'FILL' 0; transition: 200ms; }
.fav.is-selected { font-variation-settings: 'FILL' 1; }
```

```html
<span class="material-symbols-outlined fav">favorite</span>
```

### List every icon name available in a font

```bash
cat variablefont/"MaterialSymbolsOutlined[FILL,GRAD,opsz,wght].codepoints" | cut -d' ' -f1
```

```text
abc
ac_unit
access_alarm
...
```

---

## 11. Requesting a New Icon

Google generates these assets from upstream source files, so the contribution model is unusual.

> [!IMPORTANT]
> Google **does not accept pull requests** that add or modify icon files — not new icons, not fixes to existing ones. The repository is generated from upstream sources, so any hand-submitted SVG would be overwritten. Concepts are welcome; finished designs are not.

To request an icon:

1. Open a **GitHub issue** on this repository describing the icon you need.
2. Describe the *concept* rather than submitting a finished SVG.
3. If helpful, link to external examples or images that capture the "essence" of the idea. Multiple examples help convey the concept.

> [!NOTE]
> Third-party brand logos are not included for legal reasons; some that existed in the past have since been removed. New Material **Icons** (the classic set) are no longer added at all — only Material **Symbols** receives new icons.

---

## 12. Troubleshooting

### Error: icon renders as the literal icon name text

**Symptom:** The page shows the word `home` instead of a house glyph.

**Cause:** The icon-font stylesheet did not load, or the element's class does not match the loaded font.

**Solution:** Confirm the `<link>` to `fonts.googleapis.com/css2?family=...` is present and loads (check the Network tab), and that your element's class matches the set: `material-symbols-outlined`, `material-icons`, etc.

**Prevention:** Keep the stylesheet `<link>` in `<head>` and verify the family name matches the class exactly.

### Error: variable-font axes have no effect

**Symptom:** Changing `font-variation-settings` (`wght`, `FILL`, `GRAD`, `opsz`) does nothing.

**Cause:** You are using the **classic Material Icons** font, which has no variable axes — or you self-hosted a static font rather than the variable one.

**Solution:** Switch to a Material **Symbols** family, and self-host the file from `variablefont/` (the one with `[FILL,GRAD,opsz,wght]` in its name), not the static fonts from `font/`.

**Prevention:** Only the Symbols set and the `variablefont/` files are variable.

### Error: filled state shows wrong or out-of-date glyph after subsetting

**Symptom:** After subsetting the font to a list of icon names, some glyphs render in the wrong fill/stroke state.

**Cause:** Known issue with subsetting the variable font against a name list (community issue reports describe glyphs with the wrong stroke/fill state versus the un-subset font).

**Solution:** Subset by Unicode codepoint (from the `.codepoints` file) rather than by name where possible, and verify the resulting font visually. If the discrepancy persists, ship the un-subset variable font.

**Prevention:** Test subset output before deploying; keep the full `.codepoints` mapping for reference.

### Error: SVG looks different from the font glyph

**Symptom:** A standalone SVG and the same icon in the TTF/variable font don't match.

**Cause:** The SVG assets and the font binaries are generated separately and can fall briefly out of sync between updates (community issue reports note SVGs occasionally lagging TTF changes, and vice versa).

**Solution:** Prefer one source of truth per project — either the font or the SVGs — rather than mixing both for the same icon. If you need the very latest shape, the hosted Google Fonts version is the most current.

**Prevention:** Pin to a single distribution (font *or* SVG) within a given UI surface.

### Error: web preview fails to load fonts (CORS)

**Symptom:** A locally hosted preview page fails to load the font with a CORS error in the console.

**Cause:** Cross-origin restrictions when loading font files from a different origin than the page.

**Solution:** Serve the font from the same origin as the page (self-host from `variablefont/` or `font/`), or use the Google Fonts hosted stylesheet which sets the correct headers.

**Prevention:** Co-locate self-hosted fonts with your app, or rely on the hosted Google Fonts CSS.

### Error: an icon you used has disappeared

**Symptom:** An icon that previously rendered now shows nothing or a fallback box.

**Cause:** Icons are occasionally renamed, deprecated, or (for third-party logos) removed upstream. The repo is regenerated from upstream metadata, so removals propagate here.

**Solution:** Search [fonts.google.com/icons](https://fonts.google.com/icons) for a current equivalent name, and update your reference. Pin a self-hosted font version if you need an icon to remain stable.

**Prevention:** Self-host a known-good font snapshot for long-lived UIs rather than always tracking the latest.

---

## 13. FAQ

**Q: What's the difference between Material Symbols and Material Icons?**
Material Symbols is the current set, built on variable-font technology with adjustable weight, optical size, grade, and fill. Material Icons is the classic set, frozen since 2022, available in five fixed styles including two-tone. Use Symbols for new work. See [§2](#2-which-set-should-you-use).

**Q: Do I need to clone this huge repository?**
No. For most projects, link the hosted font from Google Fonts ([§1](#1-quick-start)) or download single assets from [fonts.google.com/icons](https://fonts.google.com/icons). Clone only for bulk raw assets, and use a shallow/sparse checkout ([§3](#option-c--clone-or-sparse-checkout-the-repository)).

**Q: How do I reference an icon — by name or by codepoint?**
With the icon fonts you reference by **name** using ligatures (`<span class="material-icons">home</span>`). Each name's raw Unicode codepoint is listed in the `.codepoints` file next to each font if you prefer codepoints.

**Q: Can I change the icon color and size?**
Yes — the fonts inherit CSS `color` and `font-size`. For Symbols you can also vary weight, fill, grade, and optical size via `font-variation-settings` ([§5.2](#52-controlling-material-symbols-axes-in-css)).

**Q: Why doesn't Material Symbols have a two-tone style?**
Two-tone is a classic Material Icons style only. The current Symbols set provides Outlined, Rounded, and Sharp, with fill handled by the continuous Fill axis instead.

**Q: Can I submit a new icon design via pull request?**
No. Google generates these files from upstream sources and does not accept icon PRs. Open an issue describing the *concept* instead ([§11](#11-requesting-a-new-icon)).

**Q: Is there an official npm package?**
Google does not maintain an npm package past v3 (2016). The community packages `material-symbols`, `material-icons`, `@material-design-icons/font`, and `@material-design-icons/svg` (by `@marella`) repackage these assets and are auto-updated, but are **not** monitored or vetted by Google.

**Q: What license are the icons under?**
Apache License 2.0 — free to use, remix, and re-share in your products. Attribution in your app's *about* screen is appreciated but not required. See [§14](#14-reference-tables).

**Q: Which sizes are pixel-perfect?**
For Material Symbols, only the 20 px and 24 px optical sizes are designed with perfect pixel-grid alignment. Larger sizes are for display use.

**Q: Are new icons still being added?**
Only to Material Symbols. The classic Material Icons set has not been updated since 2022 and receives no new icons, weights, or grades.

**Q: How do I get a filled icon if there's no separate "Filled" Symbols font?**
Set the `FILL` axis to `1` (`font-variation-settings: 'FILL' 1;`), or use a static `*_fill1_*` variant file from `symbols/`. The Fill axis works in all three Symbols styles.

---

## 14. Reference Tables

### Hosted font stylesheet URLs

| Set / Style | Stylesheet URL family parameter | CSS class |
|---|---|---|
| Material Symbols Outlined | `family=Material+Symbols+Outlined` | `material-symbols-outlined` |
| Material Symbols Rounded | `family=Material+Symbols+Rounded` | `material-symbols-rounded` |
| Material Symbols Sharp | `family=Material+Symbols+Sharp` | `material-symbols-sharp` |
| Material Icons (Filled) | `family=Material+Icons` | `material-icons` |
| Material Icons Outlined | `family=Material+Icons+Outlined` | `material-icons-outlined` |
| Material Icons Round | `family=Material+Icons+Round` | `material-icons-round` |
| Material Icons Sharp | `family=Material+Icons+Sharp` | `material-icons-sharp` |
| Material Icons Two Tone | `family=Material+Icons+Two+Tone` | `material-icons-two-tone` |

Base URL for all: `https://fonts.googleapis.com/css2?` followed by the family parameter.

### Static font files (`font/`)

| File | Style |
|---|---|
| `MaterialIcons-Regular.ttf` | Filled (classic) |
| `MaterialIconsOutlined-Regular.otf` | Outlined |
| `MaterialIconsRound-Regular.otf` | Round |
| `MaterialIconsSharp-Regular.otf` | Sharp |
| `MaterialIconsTwoTone-Regular.otf` | Two-tone |

### Variable font files (`variablefont/`)

| File (each also ships `.ttf` and `.codepoints`) | Style |
|---|---|
| `MaterialSymbolsOutlined[FILL,GRAD,opsz,wght].woff2` | Outlined |
| `MaterialSymbolsRounded[FILL,GRAD,opsz,wght].woff2` | Rounded |
| `MaterialSymbolsSharp[FILL,GRAD,opsz,wght].woff2` | Sharp |

### Key links

| Resource | URL |
|---|---|
| Visual icon browser | https://fonts.google.com/icons |
| Material Symbols developer guide | https://developers.google.com/fonts/docs/material_symbols/ |
| Material Icons developer guide | https://developers.google.com/fonts/docs/material_icons/ |
| Material Design guidelines | https://material.io/guidelines/ |
| License (Apache 2.0) | https://www.apache.org/licenses/LICENSE-2.0.txt |

---

_Generated June 2026 from google/material-design-icons at fef175f. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._