Material Design 3 — Web Components (`@material/web`)

Overview

Google's official M3 web component library. Framework-agnostic — works with any framework that supports Custom Elements. Built on Lit for small bundle size and interoperability.

Keywords: Material Design 3, M3, web components, @material/web, Lit, custom elements, material-web, Google official

When to Use

When you want Google's official M3 implementation
Need cross-framework components
Want standardized web components
Projects that value stability over cutting-edge features

Status: Maintenance mode — stable but not receiving major new features.

Install

npm install @material/web

Setup

Import components individually for tree-shaking:

<script type="module">
  import '@material/web/button/filled-button.js';
  import '@material/web/button/outlined-button.js';
  import '@material/web/button/text-button.js';
  import '@material/web/textfield/outlined-text-field.js';
  import '@material/web/textfield/filled-text-field.js';
  import '@material/web/checkbox/checkbox.js';
  import '@material/web/radio/radio.js';
  import '@material/web/switch/switch.js';
  import '@material/web/icon/icon.js';
  import '@material/web/fab/fab.js';
  import '@material/web/dialog/dialog.js';
  import '@material/web/menu/menu.js';
  import '@material/web/tabs/tabs.js';
  import '@material/web/tabs/primary-tab.js';
  import '@material/web/chips/chip-set.js';
  import '@material/web/chips/filter-chip.js';
  import '@material/web/progress/linear-progress.js';
  import '@material/web/progress/circular-progress.js';
  import '@material/web/select/outlined-select.js';
  import '@material/web/slider/slider.js';
  import '@material/web/list/list.js';
  import '@material/web/list/list-item.js';
  import '@material/web/navigationbar/navigation-bar.js';
  import '@material/web/navigationtab/navigation-tab.js';
</script>

Theming

Theme via CSS custom properties:

:root {
  /* Color tokens */
  --md-sys-color-primary: #6750A4;
  --md-sys-color-on-primary: #FFFFFF;
  --md-sys-color-primary-container: #EADDFF;
  --md-sys-color-secondary: #625B71;
  --md-sys-color-tertiary: #7D5260;
  --md-sys-color-error: #B3261E;
  --md-sys-color-surface: #FEF7FF;
  --md-sys-color-on-surface: #1D1B20;

  /* Typography tokens */
  --md-ref-typeface-brand: 'Roboto';
  --md-ref-typeface-plain: 'Roboto';

  /* Shape tokens */
  --md-sys-shape-corner-full: 9999px;
  --md-sys-shape-corner-large: 16px;
  --md-sys-shape-corner-medium: 12px;
  --md-sys-shape-corner-small: 8px;
}

Component Examples

Buttons

<md-filled-button>Filled</md-filled-button>
<md-outlined-button>Outlined</md-outlined-button>
<md-text-button>Text</md-text-button>
<md-filled-tonal-button>Tonal</md-filled-tonal-button>
<md-elevated-button>Elevated</md-elevated-button>

Text Fields

<md-outlined-text-field label="Email" type="email"></md-outlined-text-field>
<md-filled-text-field label="Name"></md-filled-text-field>

Navigation

<md-navigation-bar>
  <md-navigation-tab label="Home">
    <md-icon slot="active-icon">home</md-icon>
    <md-icon slot="inactive-icon">home</md-icon>
  </md-navigation-tab>
  <md-navigation-tab label="Search">
    <md-icon slot="active-icon">search</md-icon>
    <md-icon slot="inactive-icon">search</md-icon>
  </md-navigation-tab>
</md-navigation-bar>

Other Components

<md-checkbox></md-checkbox>
<md-switch></md-switch>
<md-slider></md-slider>

<md-fab label="Add">
  <md-icon slot="icon">add</md-icon>
</md-fab>

<md-linear-progress indeterminate></md-linear-progress>
<md-circular-progress indeterminate></md-circular-progress>

<md-chip-set>
  <md-filter-chip label="Option 1"></md-filter-chip>
  <md-filter-chip label="Option 2"></md-filter-chip>
</md-chip-set>

Using with Other Frameworks

@material/web can be used inside React, Vue, Svelte, and Angular since web components work in any framework. See the framework-specific M3 skills for details on integration patterns.

Checklist

Import only the components you need (tree-shaking)
Apply M3 color tokens via CSS custom properties
Configure typography typeface tokens
Handle custom element events appropriately for your framework
Test theming in both light and dark modes
Ensure proper font loading (Roboto, Material Symbols)

Resources

m3-theme.css — Complete @material/web theme template (color, typography, shape, elevation, state, motion tokens) included in this skill's directory. Copy into your project and customize.
material-theme-builder skill — Generate a custom token set from any source color.
M3 for Web: https://m3.material.io/develop/web
Documentation: https://material-web.dev/
Quick start: https://material-web.dev/about/quick-start/
Theming: https://material-web.dev/theming/material-theming/
SCSS color API: https://github.com/material-components/material-web/blob/main/color/_color.scss
Token reference: https://github.com/material-components/material-web/tree/main/tokens
GitHub: https://github.com/material-components/material-web
npm: https://www.npmjs.com/package/@material/web

m3-web-webcomponents

Material Design 3 — Web Components (@material/web)