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.

npm i @m3e/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.

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.

This 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/icon/dist/index.js"></script>

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

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

For production, use index.min.js for faster load times.

This 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.