mates-icons

Tree-shakeable Material Symbols icon components for the mates framework.

Every icon is a typed TypeScript function that returns a TemplateResult — no CDN, no font loading, no FOUC. Only the icons you import end up in your bundle.

Installation

npm install mates-icons

mates must be installed in your project as a peer dependency:

npm install mates

Usage

Import from the barrel (bundler tree-shakes unused icons)

import { HomeIcon, SearchIcon, ArrowForwardIcon } from "mates-icons";

// Standalone in a template
html`${HomeIcon({ size: 24 })}`;

// As an icon prop on any mates-ui component
Button("Search", { icon: SearchIcon({ size: 18 }) });
IconButton({ icon: ArrowForwardIcon({ fill: 1 }), label: "Next" });

Deep import (zero tree-shaking required — safest for large apps)

import { HomeIcon } from "mates-icons/home";
import { SearchIcon } from "mates-icons/search";
import { ArrowForwardIcon } from "mates-icons/arrow_forward";

Each icon lives in its own module. Deep imports guarantee that only that single icon is included in your bundle, even in bundlers with limited tree-shaking support.

API

Every icon function has the same signature:

IconName(opts?: IconOpts): TemplateResult

IconOpts

| Prop | Type | Default | Description | |---|---|---|---| | size | number \| string | 24 | Width & height. Pass a number for px (e.g. 20) or any CSS length (e.g. "1.5rem") | | color | string | "currentColor" | SVG fill color. Defaults to inheriting the surrounding text color | | fill | 0 \| 1 | 0 | 0 = outlined (default), 1 = filled |

Examples

// Default — 24px, currentColor, outlined
HomeIcon()

// Filled, 20px, explicit color
StarIcon({ fill: 1, size: 20, color: "gold" })

// Rem-based sizing
ArrowForwardIcon({ size: "1.25rem" })

// Inherits parent text color automatically
html`<span style="color: red">${FavoriteIcon({ fill: 1 })}</span>`

Icon naming convention

Icon names follow a consistent PascalCase + Icon suffix pattern derived from the Material Symbols slug:

| Material Symbols slug | Import name | |---|---| | home | HomeIcon | | search | SearchIcon | | arrow_forward | ArrowForwardIcon | | 3d_rotation | Icon3dRotation | | 10k | Icon10k | | 360 | Icon360 |

Rule: Split the slug on _, capitalise each segment, append Icon. If the result would start with a digit, prefix with Icon instead (no suffix) to keep it a valid identifier.

Using with mates-ui components

All mates-ui components that accept an icon or trailingIcon prop accept IconInput = string | TemplateResult. Icon functions return TemplateResult, so they work anywhere:

import { Button, IconButton, Chip } from "mates-ui";
import { SaveIcon, DeleteIcon, StarIcon, CheckIcon } from "mates-icons";

// Button with leading icon
Button("Save", { icon: SaveIcon({ size: 18 }) });

// Button with trailing icon, filled style
Button("Next", { trailingIcon: ArrowForwardIcon({ fill: 1, size: 18 }) });

// IconButton
IconButton({ icon: DeleteIcon(), label: "Delete", variant: "filled" });

// Chip with icon
Chip("Starred", { icon: StarIcon({ fill: 1, size: 16 }) });

Replacing the Google Fonts CDN

If you were previously loading Material Symbols via the Google Fonts CDN:

<!-- Remove this -->
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded..." rel="stylesheet" />

With mates-icons you no longer need the CDN link at all. Icons are bundled inline as SVG — they render immediately with zero network requests and work fully offline.

Bundle size

| Icons used | CDN font | mates-icons | |---|---|---| | 5 | ~4 MB (full font) | ~3 KB | | 50 | ~4 MB | ~25 KB | | 200 | ~4 MB | ~100 KB | | All 3 862 | ~4 MB | ~1.5 MB |

For typical apps using 20–100 icons, mates-icons is 40–100× smaller than the CDN font.

Generating / rebuilding icons

The icon source files are auto-generated from @material-symbols/svg-400. To regenerate after updating the upstream package:

# Install dependencies (includes @material-symbols/svg-400 as a devDep)
npm install

# Regenerate src/icons/*.ts and src/index.ts
npm run generate

# Compile to dist/
npm run build

The generate script (scripts/generate.mjs) reads the rounded-style SVGs, extracts path data for both the outlined and filled variants, and emits one .ts file per icon plus a barrel src/index.ts.

License

Apache-2.0 — same as Material Symbols.