Material Symbols Setup

Switching to Material Symbols is completely optional.

This page assumes you have gone through the initial installation steps and would like to use Material Symbols throughout the app.

Default Icon Configuration

If not done so already, update the default react-md icons to use the MaterialSymbol variants:

src/rmdConfig.tsx

 import { type ReactMDCoreConfiguration } from "@react-md/core/CoreProviders";
+import "@react-md/core/icon/configureMaterialSymbols";

 export const rmdConfig: ReactMDCoreConfiguration = {
   ssr: true,
 };

Or configure the default icons manually using configureIcons:

This is what importing @react-md/core/icon/configureMaterialSymbols does.

src/rmdConfig.tsx

 import { type ReactMDCoreConfiguration } from "@react-md/core/CoreProviders";
+import { configureIcons } from "@react-md/core/icon/config.js";
+import { MaterialSymbol } from "@react-md/core/icon/MaterialSymbol";
+
+configureIcons({
+  back: <MaterialSymbol name="keyboard_arrow_left" />,
+  clear: <MaterialSymbol name="close_small" />,
+  close: <MaterialSymbol name="close" />,
+  checkbox: <MaterialSymbol name="check_box_outline_blank" />,
+  checkboxChecked: <MaterialSymbol name="check_box" />,
+  checkboxIndeterminate: <MaterialSymbol name="indeterminate_check_box" />,
+  dropdown: <MaterialSymbol name="arrow_drop_down" />,
+  error: <MaterialSymbol name="error" />,
+  expander: <MaterialSymbol name="keyboard_arrow_down" />,
+  forward: <MaterialSymbol name="keyboard_arrow_right" />,
+  menu: <MaterialSymbol name="menu" />,
+  notification: <MaterialSymbol name="notifications" />,
+  password: <MaterialSymbol name="visibility" />,
+  radio: <MaterialSymbol name="radio_button_unchecked" />,
+  radioChecked: <MaterialSymbol name="radio_button_checked" />,
+  remove: <MaterialSymbol name="cancel" />,
+  selected: <MaterialSymbol name="check" />,
+  sort: <MaterialSymbol name="arrow_upward" />,
+  upload: <MaterialSymbol name="upload" />,
+});

 export const rmdConfig: ReactMDCoreConfiguration = {
   ssr: true,
 };

Material Symbol Configuration

The MaterialSymbol component defaults to the following configuration:

export const MATERIAL_CONFIG: MaterialConfiguration = {
  fill: 0,
  weight: 400,
  grade: 0,
  opticalSize: 48,
  family: "outlined",
  // NOTE: This is for the default `FontIcon` component, so this can be ignored
  // here
  iconFamily: "filled",
};

If your app uses different default configuration, update this object with the new defaults:

src/rmdConfig.tsx

 import { type ReactMDCoreConfiguration } from "@react-md/core/CoreProviders";
 import "@react-md/core/icon/configureMaterialSymbols";
+import { MATERIAL_CONFIG } from "@react-md/core/icon/materialConfig";

+MATERIAL_CONFIG.fill = 1;
+MATERIAL_CONFIG.weight = 500;
+MATERIAL_CONFIG.grade = 200;
+MATERIAL_CONFIG.opticalSize = 24;
+MATERIAL_CONFIG.family = "filled";

 export const rmdConfig: ReactMDCoreConfiguration = {
   ssr: true,
 };

Usage with next.js

The easiest way to use Material Symbols with next.js is to create a list of used symbol names and add it to a layout's metadata:

src/app/layout.tsx

 import { RootHtml } from "@react-md/core/RootHtml";
+import { getMaterialSymbolsUrl } from "@react-md/core/icon/getMaterialSymbolsUrl";
+import { type MaterialSymbolName } from "@react-md/core/icon/material";
+import { DEFAULT_MATERIAL_SYMBOL_NAMES } from "@react-md/core/icon/symbols";
 import { type Metadata } from "next";
 import { Roboto_Flex } from "next/font/google";
 import { type ReactElement, type ReactNode } from "react";

 import { RootProviders } from "@/components/RootProviders.js";

+const names = [
+  ...DEFAULT_MATERIAL_SYMBOL_NAMES,
+  "more_vert",
+  "light_mode",
+  "dark_mode",
+  "devices",
+  "code_off",
+  "deployed_code",
+  "code_blocks",
+  "markdown",
+  "content_copy",
+] satisfies readonly MaterialSymbolName[];

 export const metadata: Metadata = {
   title: "Your App Name",
+  icons: {
+    other: [
+      {
+        rel: "stylesheet",
+        url: getMaterialSymbolsUrl({ names }),
+      },
+    ],
+  },
 };

Usage with vite

A simple vite plugin can be installed and added to the vite.config.ts that just searches all the included files for MaterialSymbol components and extracts the material symbol name from the name prop.

npm install -D @react-md/vite-material-symbols-plugin

pnpm add -D @react-md/vite-material-symbols-plugin

yarn add -D @react-md/vite-material-symbols-plugin

vite.config.ts

 import { resolve } from 'node:path'
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react-swc'
+import { materialSymbolsPlugin } from "@react-md/vite-material-symbols-plugin";
+import "./src/rmdConfig.js";

 // https://vite.dev/config/
 export default defineConfig({
-  plugins: [react()],
+  plugins: [react(), materialSymbolsPlugin()],
   resolve: {
     alias: {
       everything: resolve(import.meta.dirname, 'src/_everything.scss'),
     },
   },
 })

Plugin Configuration

The plugin defaults to only using the defined MATERIAL_CONFIG settings, but can be updated to support a range of fill, weight, grade, and opticalSize. Here's an example that would load all ranges with all families:

vite.config.ts

 import { resolve } from 'node:path'
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react-swc'
 import { materialSymbolsPlugin } from "@react-md/vite-material-symbols-plugin";
 import "./src/rmdConfig.js";

 // https://vite.dev/config/
 export default defineConfig({
-  plugins: [react(), materialSymbolsPlugin()],
+  plugins: [
+    react(),
+    materialSymbolsPlugin({
+      fill: { min: 0, max: 1 },
+      grade: { min: -25, max: 200 },
+      weight: { min: 100, max: 700 },
+      opticalSize: { min: 20, max: 48 },
+      family: ["outlined", "rounded", "sharp"],
+    }),
+  ],
   resolve: {
     alias: {
       everything: resolve(import.meta.dirname, 'src/_everything.scss'),
     },
   },
 })

See the configuration for additional plugin options.