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). 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
2. Which Set Should You Use?
3. Installation & Access
4. Finding an Icon
5. Using Icons on the Web
6. Using Icons on Android
7. Using Icons on iOS
8. Styles, Sizes & Design Axes
9. Repository Layout Reference
10. Common Tasks
11. Requesting a New Icon
12. Troubleshooting
13. FAQ
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)

<!-- 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)

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

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.

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 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. 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, 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)

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

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

Sparse checkout (one set only)

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)

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

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.

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

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

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):

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, or use a recursive directory search in a clone:

find src -type d -name delete

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

<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

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

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

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:

.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

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

<!-- 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).

5.4 Self-hosted variable font

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

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

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:

<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:

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

For example, the outlined home symbol at 24 px:

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:

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:

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:

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

For example:

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.

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:

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

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.

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

Where {style} is one of the directory segments from §8.1, {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

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 () 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.
2. Add the stylesheet link for your chosen set/style.
3. Drop a styled <span> with the icon name.

<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).
3. Reference icons by ligature name with font-feature-settings: 'liga' enabled.

Pull a single Android vector drawable

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

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

Make a filled "favorite" toggle on the web

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

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

List every icon name available in a font

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

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

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

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

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

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.

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

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

Static font files (font/)

Variable font files (variablefont/)

Key links