material

material

Material Design 3 components for the web: as web components, as React, Vue, Svelte and Solid components, and as plain JavaScript. Written in TypeScript, with zero dependencies.

Documentation, live playgrounds and examples: md3.io

• Material 3 Expressive. Component sizes, shapes, colours and spring motion follow the Material 3 tokens.
• One implementation, every stack. A button looks and behaves the same as an element, as a framework component and as a factory.
• Zero dependencies. Installing material installs nothing else; the frameworks are optional peers.
• Server rendering. Elements and framework components render to declarative shadow DOM on Node and Bun.
• Measured sizes. A size budget per component, enforced on every pull request.

Install

npm install material

Quick start

import 'material/styles';
import { createButton, createTextField } from 'material';

const name = createTextField({ label: 'Name' });
const save = createButton({ text: 'Save', variant: 'filled' });

save.on('click', () => console.log('Saved', name.getValue()));

document.body.append(name.element, save.element);

material/styles is a stylesheet, so this needs a bundler that handles CSS imports (Vite, webpack, Bun, …). Each factory returns a DOM element and a small API; call destroy() when the view goes away.

Components

Every component comes three ways: a factory, a custom element and a framework component. Each has a page with a playground on md3.io/components.

Web components

A page imports the base stylesheet and the elements' CSS once, then registers the elements with defineAll(). After that <m-button> and the rest are HTML, in plain pages, server templates and any framework.

Form controls are form-associated: the form value, reset and validation work as on native controls. Overlays open in the browser's top layer. Guide: md3.io/docs/web-components.

React, Vue, Svelte and Solid

The framework components render the elements, load their CSS and register each one the first time it mounts. An app imports material/styles/base once for the theme. Each framework is an optional peer dependency: material uses the one your app has.

Server rendering

renderElement from material/ssr renders an element to declarative shadow DOM. Each framework has a bridge, such as material/ssr/react, that makes its components emit the same roots and hydrate.

Node and Bun are supported; worker and edge runtimes are not supported in material 3.0.0. Guide: md3.io/docs/server-rendering.

Themes

The baseline theme applies by default and follows the system light or dark preference. Eleven more are in the full stylesheet, each in light and dark, with three contrast levels:

<html data-theme="ocean" data-theme-mode="dark">

Colours, typefaces and shapes are CSS custom properties (--mtrl-sys-color-primary, …), so one declaration restyles every component that reads it. Guide: md3.io/docs/theming; the themes side by side: md3.io/styles/themes.

Sizes

What a bundler keeps, minified and gzipped (kB is 1,000 bytes), measured from the packed package. The table is refreshed at each release, and CI keeps every figure within 2% of the current build:

material publishes ESM only, so bundlers drop what you do not import. Each component's page on md3.io/components gives its size.

Browser support

Current Chrome, Edge, Firefox and Safari. The spring motion uses CSS linear() easing (Safari 17.2 or later); older browsers render every component but skip those transitions.

Upgrading

Upgrade to the latest mtrl 0.10.x first, then change the package name to material and follow the migration guide, verified against 3.0.5. It starts with silent theme fallbacks and lists renamed and removed APIs, with their replacements.

Where this came from

The package was published as mtrl up to 0.10.x, and its history before 3.0.0 was developed in floor/mtrl. The class prefix (mtrl-), the custom properties, the m- tags and the cascade layers keep their names.

Versions of material up to 1.0.4 are an earlier, separate library (GPL-3), still installable with npm install material@legacy.

Links

Documentation · Repository and full README · Changelog · Issues

License

MIT, see LICENSE.