Material Symbols SVG

Usage Guide

Learn how to install and use Material Symbols SVG in your project.

Installation

Install the package using your preferred package manager:

NPM package links:

React: @material-symbols-svg/reactVue: @material-symbols-svg/vueSvelte: @material-symbols-svg/svelteAstro: @material-symbols-svg/astroReact Native: @material-symbols-svg/react-native
npm install @material-symbols-svg/react

Basic Usage

Import icons by weight and style:

import { Home, Search, Settings } from '@material-symbols-svg/react/w400';
import { Home as HomeRounded } from '@material-symbols-svg/react/rounded/w400';

export default function App() {
  return (
    <div className="flex gap-3">
      <Home />
      <Search />
      <Settings />
      <HomeRounded />
    </div>
  );
}

Preview:

Home
Search
Settings
Home (Rounded)

Icon Styles

Material Symbols come in three styles:

import { Home } from '@material-symbols-svg/react/w400';
import { Home as HomeRounded } from '@material-symbols-svg/react/rounded/w400';
import { Home as HomeSharp } from '@material-symbols-svg/react/sharp/w400';

<Home />
<HomeRounded />
<HomeSharp />

Preview:

Outlined style
Rounded style
Sharp style

Icon Weights

Icons are available in 7 different weights (100-700):

import { Home as HomeW100 } from '@material-symbols-svg/react/w100';
import { Home as HomeW400 } from '@material-symbols-svg/react/w400';
import { Home as HomeW700 } from '@material-symbols-svg/react/w700';

<HomeW100 />
<HomeW400 />
<HomeW700 />

Preview:

w100
w200
w300
w400
w500
w600
w700

Icon Size

Control icon size using the size prop:

import { Home } from '@material-symbols-svg/react/w400';

<Home size={16} />
<Home size={24} />
<Home size={32} />
<Home size={48} />

Preview:

16px
24px
32px
48px

Icon Color

Using color prop

import { Home } from '@material-symbols-svg/react/w400';

<Home color="#ef4444" />
<Home color="royalblue" />
<Home color="rgb(34, 197, 94)" />

Preview:

#ef4444
royalblue
rgb(34, 197, 94)

Using CSS custom properties

import { Home } from '@material-symbols-svg/react/w400';

<Home className="text-rose-500" />
<Home style={{ color: 'var(--icon-color)' }} />

Import Strategy

Root imports are ergonomic, but deep imports can be safer for some frameworks and faster in development.

Astro 5: prefer deep import

The 2026-04-03 report in material-symbols-svg-test shows Astro 5 root import timing out at 90 seconds in dev startup, while deep import succeeded in 1.75 seconds. Treat deep import as the practical default for Astro 5.

React

Root import is fine for most apps. Switch to deep import when you want stricter control over bundle boundaries.

Root import

import { Home, Search } from '@material-symbols-svg/react';

<Home />
<Search />

Deep import

import { HomeW400 } from '@material-symbols-svg/react/icons/home';
import { SearchW700 } from '@material-symbols-svg/react/icons/search';

<HomeW400 />
<SearchW700 />

Vue

Root import works well in Vue 3 and Nuxt 3. Deep import is useful when you want variant-level imports.

Root import

<script setup lang="ts">
import { Home, Search } from '@material-symbols-svg/vue';
</script>

<template>
  <Home />
  <Search />
</template>

Deep import

<script setup lang="ts">
import { HomeW400 } from '@material-symbols-svg/vue/icons/home';
import { SearchW700 } from '@material-symbols-svg/vue/icons/search';
</script>

<template>
  <HomeW400 />
  <SearchW700 />
</template>

Svelte

Svelte supports both patterns cleanly. Root import is concise, deep import is better when you want exact variant ownership.

Root import

<script lang="ts">
  import { Home, Search } from '@material-symbols-svg/svelte';
</script>

<Home />
<Search />

Deep import

<script lang="ts">
  import { HomeW400 } from '@material-symbols-svg/svelte/icons/home';
  import { SearchW700 } from '@material-symbols-svg/svelte/icons/search';
</script>

<HomeW400 />
<SearchW700 />

Astro

Astro 5 should prefer deep import for development ergonomics. Astro 6 can use either, but deep import remains the safer recommendation.

Root import

---
import { Home, Search } from '@material-symbols-svg/astro';
---

<Home />
<Search />

Deep import

---
import { HomeW400 } from '@material-symbols-svg/astro/icons/home';
import { SearchW700 } from '@material-symbols-svg/astro/icons/search';
---

<HomeW400 />
<SearchW700 />

React Native

Root import is the normal default in React Native. Deep import is mainly useful when you want explicit per-icon variant imports.

Root import

import { Home, Search } from '@material-symbols-svg/react-native';

<Home />
<Search />

Deep import

import { HomeW400 } from '@material-symbols-svg/react-native/icons/home';
import { SearchW700 } from '@material-symbols-svg/react-native/icons/search';

<HomeW400 />
<SearchW700 />

Next.js Configuration

⚠️ Important for Next.js Users

Without proper configuration, Next.js development mode will load all icons, consuming significant memory and slowing down your development experience.

Add the following configuration to your next.config.js or next.config.ts. Include only the specific style/weight combinations you use in your project:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    optimizePackageImports: [
      '@material-symbols-svg/react',
      '@material-symbols-svg/react/rounded',
      '@material-symbols-svg/react/sharp',
    ],
  },
};

export default nextConfig;

React Native / Expo

React Native uses the same icon names and style structure, but runs on react-native-svg instead of the browser SVG runtime.

import { View } from 'react-native';
import { Home, Search, Settings } from '@material-symbols-svg/react-native';
import { Home as HomeRounded } from '@material-symbols-svg/react-native/rounded';

export default function App() {
  return (
    <View style={{ flexDirection: 'row', gap: 12 }}>
      <Home />
      <Search />
      <Settings />
      <HomeRounded />
    </View>
  );
}
npm install @material-symbols-svg/react-native react-native-svg

What to prepare

  • Install react-native-svg alongside @material-symbols-svg/react-native.
  • Expo projects can usually verify bundle resolution with expo export before opening simulators.
  • Check iOS and Android rendering separately when you change package generation or SVG behavior.
  • Use root import for the common path and deep import only when you need exact icon-level control.

Accessibility

Keep decorative icons hidden from assistive technology, and add explicit labels when the icon conveys meaning or triggers an action.

// Decorative icon
<Home aria-hidden="true" />

// Meaningful icon
<Home aria-label="Home" />

// Interactive icon
<button type="button" aria-label="Open settings">
  <Settings aria-hidden="true" />
</button>
  • for decorative icons
  • for meaningful icons
  • for interactive icons