Introduction

petal-elements is a library of web components that implement Material 3, including the Material 3 Expressive additions (button sizes, shape morphing, spring motion, button groups).

It is a community-maintained continuation of material-components/material-web, which is in maintenance mode. It is not an official Google project and is not affiliated with Google.

Material 3 is Google's open-source design system. Its guidelines are published at m3.material.io. This library follows them for the look and behavior of its components. The values (colors, sizes, typography, motion) come from the published Material Design tokens, not from screenshots; see Design tokens.

Web components are custom HTML elements with their own styles and behavior. They work in plain HTML and with any framework (Lit, React, Vue, Svelte, ...).

Many components in this library can replace browser elements such as <button> and <input>, including in forms.

<!-- Browser elements -->
<form>
  <label>
    Email
    <input type="email" name="email" required>
  </label>
  <label>
    Subscribe
    <input type="checkbox" name="subscribe">
  </label>

  <button type="reset">Reset</button>
  <button>Submit</button>
</form>

<!-- petal-elements -->
<form>
  <petal-outlined-text-field label="Email" type="email"
      name="email" required></petal-outlined-text-field>
  <label>
    Subscribe
    <petal-checkbox name="subscribe"></petal-checkbox>
  </label>

  <petal-text-button type="reset">Reset</petal-text-button>
  <petal-outlined-button>Submit</petal-outlined-button>
</form>

Design tokens are named design values, such as a color role or a corner size. In petal-elements they are CSS custom properties that you can set to style the components. They keep the --md- names of material-web, so existing themes keep working.

:root {
  --md-sys-color-primary: olive;
  --md-sys-color-secondary: tomato;
  --md-ref-typeface-brand: 'Open Sans';
  --md-ref-typeface-plain: system-ui;
}

See Theming for details.

• Tags start with petal- instead of md- (<petal-filled-button>), and classes with Petal instead of Md (PetalFilledButton).
• Imports come from petal-elements/... instead of @material/web/.... The file paths are the same.
• CSS custom properties keep their --md- names.
• The default token values are from the Material Design tokens v34 instead of v0.192. Most components look slightly different; see Token update v0.192 → v34.
• New, opt-in features: Material 3 Expressive features.