Material Symbols SVG / React

Usage Guide

Learn how to install and use @material-symbols-svg/react in your project.

Installation

Install the package using your preferred package manager:

npm install @material-symbols-svg/react

Basic Usage

Import icons by weight and style:

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

function App() {
  return (
    <div>
      <Home />
      <Settings />
      <HomeRounded />
    </div>
  );
}

Preview:

Home
Settings
Home (Rounded)

Icon Styles

Material Symbols come in three styles:

Outlined (Default)

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

Rounded

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

Sharp

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

Icon Weights

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

// Import icons with different weights
import { Home as HomeW100 } from '@material-symbols-svg/react/w100';
import { Home as HomeW200 } from '@material-symbols-svg/react/w200';
import { Home as HomeW300 } from '@material-symbols-svg/react/w300';
import { Home as HomeW400 } from '@material-symbols-svg/react/w400';
import { Home as HomeW500 } from '@material-symbols-svg/react/w500';
import { Home as HomeW600 } from '@material-symbols-svg/react/w600';
import { Home as HomeW700 } from '@material-symbols-svg/react/w700';

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';

function App() {
  return (
    <div>
      <Home size={16} />  {/* 16px */}
      <Home size={24} />  {/* 24px (default) */}
      <Home size={32} />  {/* 32px */}
      <Home size={48} />  {/* 48px */}
    </div>
  );
}

Preview:

16px
24px
32px
48px

Icon Color

Using color prop

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

function App() {
  return (
    <div>
      <Home color="#ff0000" />
      <Home color="blue" />
      <Home color="rgb(255, 0, 0)" />
    </div>
  );
}

Preview:

#ff0000
blue
rgb(255, 0, 0)

Using CSS classes

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

function App() {
  return (
    <div>
      <Home className="text-red-500" />
      <Home className="text-blue-600" />
      <Home className="text-green-400" />
    </div>
  );
}

Preview:

text-red-500
text-blue-600
text-green-400

Using CSS custom properties

/* CSS */
.icon-red {
  color: #ef4444;
}

.icon-blue {
  color: #3b82f6;
}

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

function App() {
  return (
    <div>
      <Home className="icon-red" />
      <Home className="icon-blue" />
    </div>
  );
}

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:

Basic Configuration (for outlined/w400 only)

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

export default nextConfig;

Advanced Configuration (variant-specific)

If you use specific styles and weights, include them explicitly:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    optimizePackageImports: [
      '@material-symbols-svg/react',
      // Add specific style packages you use in your project
      '@material-symbols-svg/react-rounded',
      '@material-symbols-svg/react-sharp',
      // Include any other packages you import
    ]
  }
};

export default nextConfig;

Example: If you import from @material-symbols-svg/react-sharp/w600, you must include '@material-symbols-svg/react-sharp' in the array.

Complete Configuration (all weights and styles)

For projects using multiple weights and styles, include all variants:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    optimizePackageImports: [
      // Base packages for each style
      '@material-symbols-svg/react',
      '@material-symbols-svg/react-rounded',
      '@material-symbols-svg/react-sharp',
      
      // Weight variants for outlined style (react)
      '@material-symbols-svg/react/w100',
      '@material-symbols-svg/react/w200',
      '@material-symbols-svg/react/w300',
      '@material-symbols-svg/react/w400',
      '@material-symbols-svg/react/w500',
      '@material-symbols-svg/react/w600',
      '@material-symbols-svg/react/w700',
      
      // Weight variants for rounded style
      '@material-symbols-svg/react-rounded/w100',
      '@material-symbols-svg/react-rounded/w200',
      '@material-symbols-svg/react-rounded/w300',
      '@material-symbols-svg/react-rounded/w400',
      '@material-symbols-svg/react-rounded/w500',
      '@material-symbols-svg/react-rounded/w600',
      '@material-symbols-svg/react-rounded/w700',
      
      // Weight variants for sharp style
      '@material-symbols-svg/react-sharp/w100',
      '@material-symbols-svg/react-sharp/w200',
      '@material-symbols-svg/react-sharp/w300',
      '@material-symbols-svg/react-sharp/w400',
      '@material-symbols-svg/react-sharp/w500',
      '@material-symbols-svg/react-sharp/w600',
      '@material-symbols-svg/react-sharp/w700',
    ]
  }
};

export default nextConfig;

💡 Configuration Tips

  • • Only include the weight variants you actually use in your project
  • • If you import from @material-symbols-svg/react/w600, include '@material-symbols-svg/react' in the array
  • • The base package is required even when importing specific weights
  • • Remove unused weight variants to keep your configuration clean

Benefits of optimizePackageImports

  • Faster development:Only loads the icons you actually import
  • Lower memory usage:Prevents loading thousands of unused icons
  • Better performance:Reduces bundle size and improves hot reload speed
  • Tree shaking:Automatically removes unused icons from production builds

Without optimizePackageImports

❌ Next.js will load all 46,000+ icon variants per package in development mode, which can consume several GB of memory and significantly slow down your development server.

With optimizePackageImports

✅ Next.js will only load the icons you actually import, keeping memory usage low and development fast.

Advanced Usage

Individual Icon Imports

Each individual icon file exports multiple weight and fill variants:

// Import specific weight and fill variants from individual icon files
import { HomeW400, HomeFillW600 } from '@material-symbols-svg/react/icons/home';
import { SettingsW400, SettingsFillW400 } from '@material-symbols-svg/react-rounded/icons/settings';

// Available exports for each icon:
// HomeW100, HomeW200, HomeW300, HomeW400, HomeW500, HomeW600, HomeW700
// HomeFillW100, HomeFillW200, HomeFillW300, HomeFillW400, HomeFillW500, HomeFillW600, HomeFillW700

Preview:

HomeW400 (outlined/w400)
SettingsW400 (rounded/w400)

📝 Individual Icon Structure

Each icon file exports 14 variants: 7 regular weights (W100-W700) and 7 filled weights (FillW100-FillW700). This gives you precise control over which specific variant you import.

Benefits of Individual Imports

  • Smaller bundle size:Only the specific variants you use are included
  • Better tree shaking:More granular control over what gets bundled
  • Clear dependencies:Explicit about which weight and fill variants you're using

Custom Styling

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

function App() {
  return (
    <Home 
      size={32}
      color="#ff6b6b"
      className="drop-shadow-lg hover:scale-110 transition-transform"
      style={{ 
        filter: 'drop-shadow(0 4px 6px rgba(0, 0, 0, 0.1))' 
      }}
    />
  );
}

Preview:

Hover to see scale effect

SVG Attributes Control

Each icon component accepts standard SVG attributes and allows you to override or add custom attributes:

Default Attributes

  • width/height: size prop value (default: 24)
  • viewBox: "0 -960 960 960" (fixed)
  • fill: "none" (SVG element)
  • xmlns: "http://www.w3.org/2000/svg" (fixed)
  • aria-hidden: "true" (accessibility)

Override and Add Attributes

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

function App() {
  return (
    <div>
      {/* Remove aria-hidden attribute to enable accessibility */}
      <Home aria-hidden={undefined} />
      
      {/* Add role attribute */}
      <Home role="img" />
      
      {/* Add data attributes or other SVG attributes */}
      <Home 
        data-testid="home-icon"
        tabIndex={0}
        focusable="true"
        aria-label="Home icon"
      />
    </div>
  );
}

💡 Accessibility Tips

  • Keep aria-hidden="true" for decorative icons
  • Add aria-label for meaningful icons
  • Use appropriate role for interactive icons