The m3e-icon component makes it easy to use Material Symbols in your application. It supports outlined, rounded, and sharp variants, as well as variable font features like fill, weight, grade, and optical size. For more information, see the Material Symbol Guide and Material Symbol Library .

The Material Symbols font is the easiest way to incorporate Material Symbols into your application. Using the Fonts CSS API, you can use variable fonts to optimize icon usage within your application. See Can I Use's Variable Fonts to determine whether your user's browser supports variable fonts.

Alternatively, the @m3e/icons package provides SVG versions of Material Symbols that register automatically with m3e-icon. See the SVG Icons section below for usage details.

import "@m3e/web/icon";

This section outlines usage examples and configuration guidance for the components in this package.

The following illustrates the basic use of the m3e-icon component. Use the name attribute to specify the name of the Material Symbol to present.

<m3e-icon name="home"></m3e-icon>

The following illustrates a link used to download a variable font for outlined icons with fill support.

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

The m3e-icon component supports appearance variants and fine-grained typographic controls for fill, weight, grade, and optical size.

Use the variant attribute to control the visual style of the icon. Supported values include: outlined (default), rounded, and sharp. Use the filled attribute to specify whether the icon is filled (1) or unfilled (0). This attribute maps to the FILL axis of the variable font.

The weight attribute adjusts the thickness and boldness of the icon's strokes. It behaves like font weight in text accepting values from 100 to 700. Use the grade attribute to adjust the stroke thickness of an icon. Supported values include: low, medium (default) and high. This attribute maps to the GRAD axis of the variable font with values like -25, 0, or 200.

The optical-size attribute supports values from 20 to 48 indicating the optical size of the icon.

As an alternative to use of variable fonts, you can use the @m3e/icons package for applications that prefer SVG-based icons. This package supplies SVG data sourced from @material-symbols/svg-400 and integrates with the existing m3e-icon component through an internal icon registry.

import "@m3e/icons/outlined/search";
import "@m3e/icons/outlined/home";
import "@m3e/icons/outlined/settings";
import "@m3e/icons/outlined/favorite";
import "@m3e/icons/outlined/notifications";

Icons are organized by Material Symbols variant families (outlined, rounded, sharp). You can register a specific icon by importing its module:

import "@m3e/icons/outlined/search";

Or register an entire variant family at once:

import "@m3e/icons/outlined";

Each icon module performs a side-effect registration with the internal registry used by m3e-icon. Once registered, the icon becomes available for rendering. If an icon is not registered, it will fall back to the Material Symbols variable font.

Icons are given the ARIA role="img", indicating that they represent meaningful visual content and should be interpreted by assistive technologies as images.

Include aria-hidden="true" if the icon is purely decorative. Otherwise, they must be labeled using aria-label or aria-labelledby.

The @m3e/web package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/web/dist/icon.js"></script>

In addition, you must use an import map to include dependencies.

<script type="importmap">
  {
    "imports": {
      "tslib": "https://cdn.jsdelivr.net/npm/tslib@2.8.1/+esm",
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.0/",
      "lit-html": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/+esm",
      "lit-html/directive.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directive.js",
      "lit-html/directives/if-defined.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/if-defined.js",
      "lit-html/directives/class-map.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/class-map.js",
      "@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/+esm",
      "@lit/reactive-element/": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/",
      "@m3e/web/core": "/node_modules/@m3e/web/dist/core.js"
    }
  }
</script>

For production builds, use the minified files to ensure optimal load performance.

The @m3e/web package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.