RobinTail/vite-plugin-material-symbols

README

vite-plugin-material-symbols

Material Symbols is a font-based alternative to SVG icons. Compared to Material Icons, which are packed into a bundle, thereby increasing its size, font-based symbols are loaded on the user side upon request.

However, the difficulty is that they are either loaded all at once, which is also quite a large volume, or it is necessary to specify a list of icon_names for filtering the font, which must also be sorted. Therefore, it is necessary to maintain the list of icons used within the application.

The plugin automates that job by determining which icons are used in the source code of the application and during the build substitutes that list into index.html for selective download from Google Font CDN, thus reducing the volume of the font downloaded by the user.

Requirements

Node.js ^22.18 || ^24 || ^26;
- use the plugin version 0.6 for Node 20;
Vite ^8
- use the plugin version 0.6 for Vite 6 and 7;

Installation

Install the plugin using your favourite package manager, for example:

pnpm add -D vite-plugin-material-symbols

Add it to the Vite configuration:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import materialSymbols from "vite-plugin-material-symbols";

export default defineConfig({
  plugins: [react(), materialSymbols()],
});

Ensure having <head> tag in your index.html.

Ensure assigning the required className to your icons. When using Material UI it can be globally configured:

const theme = createTheme({
  components: {
    MuiIcon: {
      defaultProps: {
        /* @see https://fonts.google.com/icons?icon.set=Material+Symbols */
        className: "material-symbols-outlined", // or -rounded or -sharp
      },
    },
  },
});

Usage

Consider a sample React component using MUI Icon:

import Stack from "@mui/material/Stack";
import Icon from "@mui/material/Icon";

const Component = () => (
  <Stack gap={2}>
    <Icon>home</Icon>
    <Icon>chevron_right</Icon>
    <Icon>comment</Icon>
  </Stack>
);

After running vite build, the <link> tag will be added to your index.html having the list of required icon names:

<link
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&icon_names=chevron_right,comment,home"
  rel="stylesheet"
/>

Limitations

The plugin substitutes the icon_names URL parameter ONLY in vite build mode. In vite dev (serve) mode index.html is transformed before the application source code, so that all Material Symbols are loaded.

Configuration

The plugin accepts an object of the following options:

moduleIdRegex:
  type: RegExp
  description: The regex to match module IDs that should be processed for finding icon names
  default: /\.([jt])sx?$/i # *.js, *.jsx, *.ts, *.tsx
jsxNodeRegex:
  type: RegExp
  description: The regex to match JSX nodes that should be processed in parsed AST (e.g. "jsx", "_jsx" or "jsxs")
  default: /jsx/
component:
  type: string | RegExp
  description: The name of JSX component to get the icon names from (or regex to match the component name)
  default: Icon
fontUrl:
  type: string
  description: Material Symbols CSS Provider
  # Standard settings: Outlined, no infill, 24px, weight 400
  default: https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0
paramName:
  type: string
  description: The name of the query parameter to add to the fontUrl
  default: icon_names
preload:
  type: boolean
  description: Enables higher priority for loading symbols
  default: false