material-web Documentation

Material Design Web Components

11,348 stars SCSS 37 files · ~73,554 tokens #component-#design-system#lit#lit-element#lit-html#material#material-design#material-you
RAW Doc

Technical Documentation: material-components/material-web

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

Material Web





@material/web is a library of
web components
that helps build beautiful and accessible web applications. It uses
Material 3, the latest version of Google's
open-source design system.

Note:
MWC is in maintenance mode pending new maintainers.

Resources

Quick start

Tip: Using Angular? We recommend using
Angular Material components
instead.

This code snippet is a buildless example that loads @material/web from a CDN.
Check out the quick start guide to install and build
for production.

html
<head>
  <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap" rel="stylesheet">
  <script type="importmap">
    {
      "imports": {
        "@material/web/": "https://esm.run/@material/web/"
      }
    }
  </script>
  <script type="module">
    import '@material/web/all.js';
    import {styles as typescaleStyles} from '@material/web/typography/md-typescale-styles.js';

    document.adoptedStyleSheets.push(typescaleStyles.styleSheet);
  </script>
</head>
<body>
  <h1 class="md-typescale-display-medium">Hello Material!</h1>
  <form>
    <p class="md-typescale-body-medium">Check out these controls in a form!</p>
    <md-checkbox></md-checkbox>
    <div>
      <md-radio name="group"></md-radio>
      <md-radio name="group"></md-radio>
      <md-radio name="group"></md-radio>
    </div>

    <md-outlined-text-field label="Favorite color" value="Purple"></md-outlined-text-field>

    <md-outlined-button type="reset">Reset</md-outlined-button>
  </form>
  <style>
    form {
      display: flex;
      flex-direction: column;
      align-items: flex-start;
      gap: 16px;
    }
  </style>
</body>

Overview (`internal/README.md`)

Internal

WARNING ⚠️ This folder contains internal features that have limited support.
Proceed with caution when using them in a project.

Breaking changes may occur that do not bump the major version (vX.0.0).

Overview (`labs/README.md`)

Labs 🚧

WARNING ⚠️ This folder contains experimental features that are not recommended
for production.

Breaking changes may occur that do not bump the major version (vX.0.0).

Overview (`docs/theming/README.md`)

Theming

Material Design theming
creates unique branded products with familiar patterns and accessible
interactions.

collage of views of a mobile UI that show a user's setting and preference fora green primary color flows through system UIharmoniously

Tokens

Material is expressed in
design tokens,
which are the building blocks of all UI elements.

Each component token maps to a system token, which has a concrete reference
value.

A diagram showing the heirachy of component tokens to system tokens toreferencetokens

On the web, design tokens are
CSS custom properties
and can be scoped with CSS selectors.

css
.square-buttons {
  /* Changes all <md-filled-button> instances matching the selector */
  --md-filled-button-container-shape: 0px;
}

Reference

Reference tokens hold concrete values, such as a hex color, pixel size, or font
family name.

Typeface

--md-ref-typeface tokens can be used to change font
families and weights across all system and component tokens.

css
:root {
  --md-ref-typeface-brand: 'Open Sans';
  --md-ref-typeface-plain: 'Open Sans';
}

Palette

MWC does not currently support --md-ref-palette tokens.

System

System tokens define decisions and roles that give the design system its
character, from color and typography, to elevation and shape.

Color

--md-sys-color tokens define dynamic color roles that map
to components. See the color guide for more details.

css
:root {
  --md-sys-color-primary: red;
  --md-sys-color-secondary: blue;
}

Typography

--md-sys-typescale tokens define typescale roles
that map to components. See the typography guide for more
details.

css
:root {
  --md-sys-typescale-body-medium-size: 1rem;
  --md-sys-typescale-body-medium-line-height: 1.5rem;
}

Shape

--md-sys-shape tokens define corner shapes used in
components. See the shape guide for more details.

css
:root {
  --md-sys-shape-corner-small: 4px;
  --md-sys-shape-corner-medium: 6px;
  --md-sys-shape-corner-large: 8px;
}

Motion

MWC does not currently support --md-sys-motion tokens.

Component

Component tokens are design attributes assigned to elements. They can be system
tokens or concrete values.

css
:root {
  --md-filled-button-container-shape: 0px;
}

md-filled-button.error {
  --md-filled-button-container-color: var(--md-sys-color-error);
  --md-filled-button-label-text-color: var(--md-sys-color-on-error);
}

Refer to each components' documentation for available tokens.

Note: unlike --md-ref-* and --md-sys-* tokens, which are prefixed with
ref and sys, component tokens are not prefixed with comp.

Overview (`migrations/v2/README.md`)

Breaking changes from v1 to v2

ARIA attribute querySelector

What changed?

role and aria-* attributes now shift at runtime to data-role and
data-aria-* attributes. This fixes a screen reader bug around labels
announcing more than once.

What broke?

Using querySelector or querySelectorAll with [role] or [aria-*]
attribute selectors.

html
<md-checkbox aria-label="Agree"></md-checkbox>
<script>
  const agreeCheckbox = document.querySelector(
    'md-checkbox[aria-label="Agree"]'
  );
  // `agreeCheckbox` is null!
</script>

How to fix?

Provide selector strings to ariaSelector() before querying.

ts
import {ariaSelector} from '@material/web/migrations/v2/query-selector-aria';

const agreeCheckbox = document.querySelector(
  ariaSelector('md-checkbox[aria-label="Agree"]')
);

Note: Element APIs, such as element.getAttribute('role') and
element.ariaLabel will continue to work as expected.

Sass `tokens.md-comp-*-values()` include custom properties by default

What changed?

Sass component token functions return a var() with the component's custom
property, instead of just a value.

scss
@use '@material/web/tokens';

$checkbox-tokens: tokens.md-comp-checkbox-values();
// (
//   // 'icon-size': 18px, // Before
//   'icon-size': var(--md-checkbox-icon-size, 18px), // After
// )

What broke?

Sass token values from tokens.md-comp-*-values() functions are var()
functions instead of CSS values. This may introduce additional unnecessary CSS
or break Sass.

scss
@use '@material/web/tokens';

$checkbox-tokens: tokens.md-comp-checkbox-values();

$double-icon-size: math.mult(map.get($checkbox-tokens, 'icon-size'), 2);
// @error var(--md-checkbox-icon-size, 18px) is not a number.

How to fix?

Add the parameter $exclude-custom-properties: true to the values function.

scss
@use '@material/web/tokens';

$checkbox-tokens: tokens.md-comp-checkbox-values($exclude-custom-properties: true);
// (
//   'icon-size': 18px,
// )

Overview (`switch/internal/README.md`)

Switch

DOM structure

html
<button class="switch">
  <div class="track">
    ::before
    <div class="handle">
      ::before
      <div class="icons">
      </div>
    </div>
  </div>
  <input type="checkbox" aria-hidden="true">
</button>

.switch

This is the outermost button. It holds the track and the input checkbox.

NOTE: This is intentionally left without a border to make the focus-ring simpler
to apply.

.track

This is the track. It contains the track selected styles.

.track::before

This element contains the track unselected styles. Its opacity is set to 0
when the switch is selected.

.handle

This is the handle. It contains the styles of selected styles.

.handle::before

This element contains the handle unselected styles. Its opacity is set to 0
when the switch is selected.

Animations

  • opacity on .track::before
    • Why? setting opacity will change between selected and unselected track
  • opacity on .handle::before
    • Why? setting opacity will change between selected and unselected handle
  • transform (scale) on .handle
    • Why? This animates the growing & shrinking of the handle.
  • margin-inline-start & margin-inline-end on .handle
    • Why? This animates the position of the handle.

Overview (`tokens/versions/README.md`)

This folder contains auto-generated files for the Material Design tokens.

@material/web/tokens/versions is useful for custom implementations and
experimentations with the Material Design system.

WARNING: @material/web/tokens/versions/ may introduce breaking changes
at any point across minor and patch updates.

Most users should ignore this folder and use other APIs provided by
@material/web/tokens.

To avoid unexpected breakages when using these files, save the exact version
of @material/web (e.g. use --save-exact for @2.0.0 instead of
@^2.0.0).

Overview (`labs/gb/components/tabs/README.md`)

Tabs

Classes

Class Applied to Purpose
.tabs Container Tablist container layout and paints the active indicator.
.tabs-secondary Container Secondary variant (applied alongside .tabs).
.tab Tab element Tab item layout, typography, and interactive states.
.tab-label Label wrapper Required label element inside .tab. Bare text is not supported.
.tab-badge Badge element Optional badge positioning modifier (applied alongside .badge).
.focus-ring-inner Tab element Focus ring contract for inner focus indicator styling.
.ripple Tab element Ripple contract for state layer styling.
.selected Tab element Selected tab state. Matches [aria-selected="true"] and :state(selected).

Selected tabs match :is(.selected, [aria-selected="true"], :state(selected)).

Child DOM order

Child elements within a tab must be authored in visual order (icon, label,
badge) to satisfy CSS anchor geometry.

Element Baseline DOM Reference element Notes
Icon <md-gb-icon> <md-gb-icon> (default slot) Unclassed child. .tab sets --md-icon-* metrics and color.
Label `` slot="label" Required. Bare text is not supported.
Badge `` slot="badge" Optional badge inside a tab.

Baseline DOM

Baseline DOM documents the minimal markup contract (structure, roles, and
attributes) required to represent the component, rather than a feature-complete
widget.

html
<div class="tabs" role="tablist" focusgroup="tablist inline">
  <button class="tab focus-ring-inner ripple selected" role="tab" aria-selected="true">
    <md-gb-icon>flight</md-gb-icon>
    <span class="tab-label">Flights</span>
    <span class="badge tab-badge">3</span>
  </button>
  <button class="tab focus-ring-inner ripple" role="tab" aria-selected="false">
    <span class="tab-label">Trips</span>
  </button>
</div>

Add class="tabs-secondary" alongside .tabs for the secondary variant. Tabs
scroll when the container overflows; there is no scrollable modifier.

Overflow scroll setup

Hand-authored baseline DOM does not automatically scroll partially-visible tabs
into view on focus. Consumers must invoke setupTabs() on the tablist element
to attach the framework-agnostic focus listener:

ts
import {setupTabs} from '@material/web/labs/gb/components/tabs/tabs.js';

const tabsElement = document.querySelector('.tabs');
setupTabs(tabsElement);

The reference custom element and the tabs() Lit directive call setupTabs()
automatically.

Reference implementation

<md-gb-tabs> and <md-gb-tab> provide a reference custom element
implementation of the tabs contract.

html
<md-gb-tabs variant="secondary">
  <md-gb-tab selected tabpanel="flights">
    <md-gb-icon>flight</md-gb-icon>
    <span slot="label">Flights</span>
    <span class="badge tab-badge" slot="badge">3</span>
  </md-gb-tab>
  <md-gb-tab tabpanel="trips">
    <span slot="label">Trips</span>
  </md-gb-tab>
</md-gb-tabs>
<md-aria-tabpanel id="flights">...</md-aria-tabpanel>
<md-aria-tabpanel id="trips">...</md-aria-tabpanel>

``

API Type Description
variant / .variant 'primary' | 'secondary' Default 'primary'. Visual variant of the tablist.
autoselect / .autoSelect boolean Default false. Automatically select a tab when focused.
.selectedTab HTMLElement | null Currently selected tab element (or null if empty).
selectedtabindex / .selectedTabIndex number Index of the currently selected tab.
.tabs HTMLElement[] Read-only. Array of child tab elements.
@change Event Fired when tab selection changes.
[default] Slot Children container for <md-gb-tab> elements.

CSS custom properties

Custom property Description
--active-indicator-color Color of the active indicator bar.
--active-indicator-height Height of the active indicator bar.
--active-indicator-inset Horizontal inset of the active indicator.
--active-indicator-min-length Minimum width of the active indicator container.
--active-indicator-shape Border radius shape of the active indicator.
--container-color Background color of the container.
--container-height Minimum height of the container.
--container-shape Border radius shape of the container.
--divider-color Color of the bottom divider.
--divider-thickness Thickness of the bottom divider.

``

API Type Description
selected / .selected boolean Default false. Whether the tab is selected.
tabpanel / .tabpanel string Default ''. ID of the associated md-aria-tabpanel.
:state(selected) CSS state Applied when the tab is selected.
[default] Slot Leading icon (e.g. <md-gb-icon>).
label Slot Tab label element.
badge Slot Optional badge (e.g. ``).

CSS custom properties

Custom property Description
--badge-space Inline space before the badge.
--focus-indicator-clearance Clearance above indicator for focus ring.
--focus-indicator-inset Focus ring inset.
--focus-indicator-shape Focus ring border radius.
--icon-badge-inset Inset for badge anchored to icon.
--icon-color Icon color.
--icon-label-space Inline space between icon and label.
--icon-size Icon size.
--label-text Typography shorthand for the label.
--label-text-axes Variable font axes settings for the label.
--label-text-color Label text color.
--label-text-tracking Letter spacing for the label.
--leading-space Inline padding at the start of the tab.
--stacked-icon-label-space Space between stacked icon and label.
--tab-scroll-margin Scroll margin for focus-driven scroll-into-view.
--trailing-space Inline padding at the end of the tab.

Intro (`docs/intro.md`)

Intro to Material Web Components

Material web, also known as Material Web Components or MWC, is a library of
web components
that follows Google's Material Design
guidelines.

What is Material?

Material Design is a design system built and supported by Google designers and
developers. Guidelines for building Material apps and components are published
on material.io.

The latest version, Material 3, enables personal, adaptive, and expressive
experiences – from dynamic color and enhanced accessibility, to foundations for
large screen layouts and design tokens.

What are web components?

Web components
are custom HTML elements with encapsulated styles and behavior. They work across
many different frameworks (such as Lit, React, Vue, and Svelte) as well as web
environments (such as Eleventy, Wordpress, and Ruby on Rails).

Many components in
this library are drop-in replacements for browser elements like and.

html
<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>


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

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

What are tokens?

Design tokens
are the building blocks of all UI elements. In MWC, tokens are
CSS custom properties
that can be used to style components.

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

Quick Start (`docs/quick-start.md`)

Quick start

CDN

For fast prototyping, we recommend using esm.run,
a CDN that allows you to use @material/web without installing and building
from NPM.

html
<head>
  <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap" rel="stylesheet">
  <script type="importmap">
    {
      "imports": {
        "@material/web/": "https://esm.run/@material/web/"
      }
    }
  </script>
  <script type="module">
    import '@material/web/all.js';
    import {styles as typescaleStyles} from '@material/web/typography/md-typescale-styles.js';

    document.adoptedStyleSheets.push(typescaleStyles.styleSheet);
  </script>
</head>
<body>
  <h1 class="md-typescale-display-medium">Hello Material!</h1>
  <form>
    <p class="md-typescale-body-medium">Check out these controls in a form!</p>
    <md-checkbox></md-checkbox>
    <div>
      <md-radio name="group"></md-radio>
      <md-radio name="group"></md-radio>
      <md-radio name="group"></md-radio>
    </div>
    <md-outlined-text-field label="Favorite color" value="Purple"></md-outlined-text-field>
    <md-outlined-button type="reset">Reset</md-outlined-button>
  </form>
  <style>
    form {
      display: flex;
      flex-direction: column;
      align-items: flex-start;
      gap: 16px;
    }
  </style>
</body>

For production, follow the install and build steps
below.

Install

Install Material web components using
npm and node.

shell
npm install @material/web

Import

Import element definitions from
@material/web/<component>/<component-variant>.js.

js
// index.js
import '@material/web/button/filled-button.js';
import '@material/web/button/outlined-button.js';
import '@material/web/checkbox/checkbox.js';

Usage

Use the <component-name> tag in HTML markup. Refer to the
component docs for more guidance on using each component.

Playground

html
<script type="module" src="./index.js"></script>

<label>
  Material 3
  <md-checkbox checked></md-checkbox>
</label>

<md-outlined-button>Back</md-outlined-button>
<md-filled-button>Next</md-filled-button>

Building

Material web components uses bare module specifiers that must be resolved with
tools until import maps are
adopted.

We recommend following
lit.dev's modern build for production
for a more in-depth build guide.

Rollup quick start

For a quick start, we recommend using Rollup
to resolve bare module specifiers into a bundled file.

Install Rollup and a plugin to resolve bare module specifiers.

shell
npm install rollup @rollup/plugin-node-resolve

Create a bundle from an entrypoint index.js file and use it in a <script>
"src" attribute.

shell
npx rollup -p @rollup/plugin-node-resolve index.js -o bundle.js
html
<script src="./bundle.js"></script>

Roadmap (`docs/roadmap.md`)

Roadmap

This roadmap describes current, future, and past goals for Material Web
Components.

Current

MWC is currently in maintenance mode,
see this announcement
for more details.

There is no current work planned for new features or components. Bug fixes or
other contributions may be added on a case-by-case basis.

Future

Note: No future work is planned while MWC is in
maintenance mode.
These roadmap items represent what used to be planned.

New components

These are components we have not built yet.

  • Autocomplete
  • Badge
  • Banner
  • Bottom app bar
  • Bottom sheet
  • Card
  • Data table
  • Date picker
  • Navigation bar
  • Navigation drawer
  • Navigation rail
  • Search
  • Segmented button
  • Snackbar
  • Time picker
  • Top app bar
  • Tooltip

Expand Material Design tokens

We are adding shape and motion system tokens to support building expressive
Material experiences.

We also want to make it easier to use Material Design tokens, such as applying
Material typescale, shape, and color to your own components.

Density and spacing tokens

Density allows components to take up less vertical space for larger displays.
While we have some spacing tokens already, we need a comprehensive spacing
system to fully support density across components.

Create TSX components

TSX is a popular
language extension for frameworks like React. We want to
make it easier and more seamless to use Material Web Components in TSX.

Explore Material Design layouts

Components are only part of the story to build fully expressive Material Design
applications. We want to explore ways to support building applications that
follow
Material's layout patterns.

Past

Follow accessibility best practices

Completed in Q1 2024

Everyone should be able to access and enjoy the web. We want our components to
help others build accessible experiences. The following screen readers are fully
supported:

  • VoiceOver
  • Talkback
  • ChromeVox
  • JAWS
  • NVDA

Cards and more

Completed in Q4 2023

Material 1.0

Completed in Q3 2023

  • Features
    • ✅ Color theming
    • ✅ Typography theming
  • Components
    • ✅ Button
    • ✅ FAB
    • ✅ Icon button
    • ✅ Checkbox
    • ✅ Chips
    • ✅ Dialog
    • ✅ Divider
    • ✅ Elevation
    • ✅ Focus ring
    • ✅ List
    • ✅ Menu
    • ✅ Progress indicators
    • ✅ Radio
    • ✅ Ripple
    • ✅ Select
    • ✅ Slider
    • ✅ Switch
    • ✅ Tabs
    • ✅ Text field

Size (`docs/size.md`)

Sizes

This doc tracks important size metrics for Material Web Components.

Sizes are tracked in bundles. A bundle is a single .js file for one or more
components that includes all of the JavaScript and CSS needed, minus external
dependencies. We track three metrics:

  • gzip - minified and compressed. This impacts download size, which can
    take longer over slow networks.

  • minified - minified and unpacked. This impacts the time it takes a page
    to be interactive, which can take longer on some devices.

  • % CSS - the amount of CSS compared to JavaScript. The bundle includes
    both JS and CSS, so this helps track changes to JS logic and CSS styles
    separately.

Last updated 2025-08-20.

Component gzip minified % CSS Import
All 72.1kb 455.5kb 64% CSS @material/web/all.js
Common 53.7kb 287.6kb 52% CSS @material/web/common.js
Button 8.4kb 48.4kb 64% CSS
7.0kb 29.0kb 47% CSS @material/web/button/elevated-button.js
7.0kb 28.9kb 47% CSS @material/web/button/filled-button.js
7.0kb 29.3kb 48% CSS @material/web/button/filled-tonal-button.js
6.8kb 27.4kb 46% CSS @material/web/button/outlined-button.js
6.6kb 25.8kb 43% CSS @material/web/button/text-button.js
Checkbox 7.0kb 27.3kb 37% CSS @material/web/checkbox/checkbox.js
Chips 10.5kb 62.6kb 62% CSS
5.1kb 17.7kb 21% CSS @material/web/chips/chip-set.js
6.8kb 28.5kb 49% CSS @material/web/chips/assist-chip.js
8.3kb 38.6kb 53% CSS @material/web/chips/filter-chip.js
7.8kb 35.4kb 52% CSS @material/web/chips/input-chip.js
6.8kb 28.9kb 49% CSS @material/web/chips/suggestion-chip.js
Dialog 5.0kb 17.1kb 27% CSS @material/web/dialog/dialog.js
Divider 0.6kb 1.3kb 34% CSS @material/web/divider/divider.js
Elevation 0.6kb 1.7kb 62% CSS @material/web/elevation/elevation.js
Fab 7.2kb 38.5kb 66% CSS
6.9kb 34.0kb 63% CSS @material/web/fab/fab.js
6.1kb 25.7kb 50% CSS @material/web/fab/branded-fab.js
Field 6.1kb 41.5kb 83% CSS
4.7kb 25.5kb 74% CSS @material/web/field/filled-field.js
5.0kb 27.7kb 76% CSS @material/web/field/outlined-field.js
Focus 1.5kb 5.4kb 49% CSS @material/web/focus/md-focus-ring.js
Icon 0.7kb 1.3kb 47% CSS @material/web/icon/icon.js
Icon button 7.7kb 44.9kb 64% CSS
6.2kb 24.8kb 40% CSS @material/web/iconbutton/icon-button.js
6.4kb 26.9kb 44% CSS @material/web/iconbutton/filled-icon-button.js
6.4kb 27.5kb 45% CSS @material/web/iconbutton/filled-tonal-icon-button.js
6.4kb 26.5kb 44% CSS @material/web/iconbutton/outlined-icon-button.js
List 7.3kb 28.4kb 33% CSS
1.6kb 4.7kb 4% CSS @material/web/list/list.js
6.1kb 23.9kb 39% CSS @material/web/list/list-item.js
Menu 14.1kb 55.9kb 22% CSS
8.2kb 30.2kb 17% CSS @material/web/menu/menu.js
6.8kb 26.5kb 36% CSS @material/web/menu/menu-item.js
8.6kb 33.0kb 11% CSS @material/web/menu/sub-menu.js
Progress 3.8kb 14.8kb 65% CSS
2.9kb 9.6kb 56% CSS @material/web/progress/linear-progress.js
2.5kb 8.3kb 51% CSS @material/web/progress/circular-progress.js
Radio 6.6kb 24.4kb 28% CSS @material/web/radio/radio.js
Ripple 2.7kb 7.7kb 13% CSS @material/web/ripple/ripple.js
Select 26.6kb 146.9kb 56% CSS
18.8kb 93.6kb 47% CSS @material/web/select/filled-select.js
19.0kb 94.1kb 47% CSS @material/web/select/outlined-select.js
6.9kb 27.6kb 35% CSS @material/web/select/select-option.js
Slider 9.9kb 43.2kb 45% CSS @material/web/slider/slider.js
Switch 8.0kb 33.5kb 45% CSS @material/web/switch/switch.js
Tabs 7.7kb 35.2kb 50% CSS
6.1kb 21.9kb 25% CSS @material/web/tabs/tabs.js
6.2kb 25.6kb 49% CSS @material/web/tabs/primary-tab.js
6.1kb 25.2kb 48% CSS @material/web/tabs/secondary-tab.js
Text field 14.7kb 97.2kb 73% CSS
11.5kb 64.1kb 61% CSS @material/web/textfield/filled-text-field.js
11.7kb 64.6kb 61% CSS @material/web/textfield/outlined-text-field.js

Support (`docs/support.md`)

Support

Browsers

MWC aims to support the latest two major versions of browsers at the time of
each release.

Current browsers and versions supported:

Browser Version
Chrome 120 +
Edge 120 +
Firefox 119 +
Safari* 16.4 +

* previous versions of Safari may be supported with an
ElementInternals polyfill.

FAQ

If you have a question that isn't listed here, consider asking it so we can
include it!

How do I change the color of a button?

Many components have multiple tokens for a color, including "hover", "focus",
and "pressed" states.

Use --md-sys-color-* tokens to change the key color that the component uses.

css
/* Buttons use the `primary` key color */
md-filled-button.spooky {
  --md-sys-color-primary: black;
  --md-sys-color-on-primary: yellow;
}

md-filled-button.error {
  --md-sys-color-primary: var(--md-sys-color-error);
  --md-sys-color-on-primary: var(--md-sys-color-on-error);
}

Why does my color change on hover/focus/pressed?

Many colors have multiple tokens, including "hover", "focus", and "pressed"
states.

Rather than setting all of them, or use the --md-sys-color-* token that the
component maps to (see the previous question).

Why doesn't `prefers-color-scheme: dark` work?

It's up to the app to decide when and how dark mode is applied. Any selector can
be used with --md-sys-color-* dark theme tokens to scope how the changes
apply.

For example, using Sass:

scss
@use '@material/web/color/color';

:root {
  @media (prefers-color-scheme: dark) {
    @include color.dark-theme;
  }
}

Why not automatically? Not all apps need dark mode, and the CSS size for
automatically supporting it is much higher and not as flexible.

See
How do I use --md-sys-* custom properties in my styles?
for more info on how to generate a set of dark theme tokens.

How do I use `--md-sys-*` custom properties in my styles?

  • Use Sass APIs.

    scss
    @use '@material/web/color/color';
@use '@material/web/color/typography';

:root {
  @include color.light-theme;
  @include typography.theme;

  @media (prefers-color-scheme: dark) {
    @include color.dark-theme;
  }
}

  • Use the
    Material theme builder Figma plugin
    to generate a color scheme.

  • Use the
    material-color-utilities library
    to generate color schemes at runtime.

How do I customize an `` element that is inside another component?

Use CSS ::part()s
to access sub-components. The part name is the sub-component's tag name without
the "md-" prefix.

css
md-checkbox::part(focus-ring) {
  width: 32px;
  height: 32px;
}

Components Button (`docs/components/button.md`)

Buttons

This documentation is fully rendered on the
Material Web catalog.

Buttons help people
initiate actions, from sending an email, to sharing a document, to liking a
post.

There are five types of common buttons: elevated, filled, filled tonal,
outlined, and text.

Types

  1. Elevated button
  2. Filled button
  3. Filled tonal button
  4. Outlined button
  5. Text button

Usage

Buttons have label text that describes the action that will occur if a user taps
a button.

An outlined button with the text "Back" next to a filled button with the text"Complete"

html
<md-outlined-button>Back</md-outlined-button>
<md-filled-button>Complete</md-filled-button>

Icon

An icon may optionally be added to a button to help communicate the button's
action and help draw attention.

A tonal button with a right arrow send icon with text 'send' and a text buttonwith the text 'open' with a trailing icon arrowbox

html
<md-filled-tonal-button>
  Send
  <svg slot="icon" viewBox="0 0 48 48"><path d="M6 40V8l38 16Zm3-4.65L36.2 24 9 12.5v8.4L21.1 24 9 27Zm0 0V12.5 27Z"/></svg>
</md-filled-tonal-button>

<md-text-button trailing-icon>
  Open
  <svg slot="icon" viewBox="0 0 48 48"><path d="M9 42q-1.2 0-2.1-.9Q6 40.2 6 39V9q0-1.2.9-2.1Q7.8 6 9 6h13.95v3H9v30h30V25.05h3V39q0 1.2-.9 2.1-.9.9-2.1.9Zm10.1-10.95L17 28.9 36.9 9H25.95V6H42v16.05h-3v-10.9Z"/></svg>
</md-text-button>

Accessibility

Add an
aria-label
attribute to buttons whose labels need a more descriptive label.

html
<md-elevated-button aria-label="Add a new contact">Add</md-elevated-button>

Focusable and disabled

By default, disabled buttons are not focusable with the keyboard, while
"soft-disabled" buttons are. Some use cases encourage focusability of disabled
toolbar items to increase their discoverability.

See the
ARIA guidelines on focusability of disabled controls
for guidance on when this is recommended.

html
<div role="toolbar">
  <md-text-button>Copy</md-text-button>
  <md-text-button>Cut</md-text-button>
  
  <md-text-button soft-disabled>Paste</md-text-button>
</div>

Elevated button

Elevated buttons
are essentially filled tonal buttons with a shadow. To prevent shadow creep,
only use them when absolutely necessary, such as when the button requires visual
separation from a patterned background.

html
<md-elevated-button>Elevated</md-elevated-button>

Filled button

Filled buttons
have the most visual impact after the FAB, and should be used for important,
final actions that complete a flow, like Save, Join now, or Confirm.

html
<md-filled-button>Filled</md-filled-button>

Filled tonal button

A
filled tonal button
is an alternative middle ground between filled and outlined buttons. They're
useful in contexts where a lower-priority button requires slightly more emphasis
than an outline would give, such as "Next" in an onboarding flow.

html
<md-filled-tonal-button>Tonal</md-filled-tonal-button>

Outlined button

Outlined buttons
are medium-emphasis buttons. They contain actions that are important, but aren’t
the primary action in an app.

html
<md-outlined-button>Outlined</md-outlined-button>

Text button

Text buttons
are used for the lowest priority actions, especially when presenting multiple
options.

html
<md-text-button>Text</md-text-button>

Theming

Button supports Material theming and can be customized
in terms of color, typography, and shape.

Elevated button tokens

Token Default value
--md-elevated-button-container-color --md-sys-color-surface
--md-elevated-button-container-shape --md-sys-shape-corner-full
--md-elevated-button-label-text-color --md-sys-color-on-surface
--md-elevated-button-label-text-font --md-sys-typescale-label-large-font

Elevated button example

html
<style>
:root {
  --md-elevated-button-container-shape: 0px;
  --md-elevated-button-label-text-font: system-ui;
  --md-sys-color-surface-container-low: #FAFDFC;
  --md-sys-color-primary: #191C1C;
}
</style>

<md-elevated-button>Elevated</md-elevated-button>

Filled button tokens

Token Default value
--md-filled-button-container-color --md-sys-color-primary
--md-filled-button-container-shape --md-sys-shape-corner-full
--md-filled-button-label-text-color --md-sys-color-on-primary
--md-filled-button-label-text-font --md-sys-typescale-label-large-font

Filled button example

html
<style>
:root {
  --md-filled-button-container-shape: 0px;
  --md-filled-button-label-text-font: system-ui;
  --md-sys-color-primary: #006A6A;
  --md-sys-color-on-primary: #FFFFFF;
}
</style>

<md-filled-button>Filled</md-filled-button>

Filled tonal button tokens

Token Default value
--md-filled-tonal-button-container-color --md-sys-color-secondary-container
--md-filled-tonal-button-container-shape --md-sys-shape-corner-full
--md-filled-tonal-button-label-text-color --md-sys-color-on-secondary-container
--md-filled-tonal-button-label-text-font --md-sys-typescale-label-large-font

Filled tonal button example

html
<style>
:root {
  --md-filled-tonal-button-container-shape: 0px;
  --md-filled-tonal-button-label-text-font: system-ui;
  --md-sys-color-secondary-container: #CCE8E7;
  --md-sys-color-on-secondary-container: #051F1F;
}
</style>

<md-filled-tonal-button>Tonal</md-filled-tonal-button>

Outlined button tokens

Token Default value
--md-outlined-button-outline-color --md-sys-color-outline
--md-outlined-button-container-shape --md-sys-shape-corner-full
--md-outlined-button-label-text-color --md-sys-color-primary
--md-outlined-button-label-text-font --md-sys-typescale-label-large-font

Outlined button example

html
<style>
:root {
  --md-outlined-button-container-shape: 0px;
  --md-outlined-button-label-text-font: system-ui;
  --md-sys-color-primary: #006A6A;
  --md-sys-color-outline: #6F7979;
}
</style>

<md-outlined-button>Outlined</md-outlined-button>

Text button tokens

Token Default value
--md-text-button-label-text-color --md-sys-color-primary
--md-text-button-label-text-font --md-sys-typescale-label-large-font

Text button example

html
<style>
:root {
  --md-text-button-label-text-font: system-ui;
  --md-sys-color-primary: #006A6A;
}
</style>

<md-text-button>Text</md-text-button>

API

MdElevatedButton `<md-elevated-button>`

Properties

Property Attribute Type Default Description
softDisabled soft-disabled boolean false Whether or not the button is "soft-disabled" (disabled but still focusable).Use this when a button needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
href href string '' The URL that the link button points to.
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the button is used as a link (href is set).
target target "" | "_blank" | "_parent" | "_self" | "_top" '' Where to display the linked href URL for a link button. Common options include _blank to open in a new tab.
trailingIcon trailing-icon boolean false Whether to render the icon at the inline end of the label rather than the inline start.Note: Link buttons cannot have trailing icons.
hasIcon has-icon boolean false Whether to display the icon or not.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
type type string 'submit' A string indicating the form submission behavior of the element.- submit: The element submits the form. This is the default value if the attribute is not specified, or if it is dynamically changed to an empty or invalid value. - reset: The element resets the form. - button: The element does nothing.
value value string '' The value of the button. When combined with a name, the submitting button's name/value will be added to the form.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.

MdFilledButton `<md-filled-button>`

Properties

Property Attribute Type Default Description
softDisabled soft-disabled boolean false Whether or not the button is "soft-disabled" (disabled but still focusable).Use this when a button needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
href href string '' The URL that the link button points to.
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the button is used as a link (href is set).
target target "" | "_blank" | "_parent" | "_self" | "_top" '' Where to display the linked href URL for a link button. Common options include _blank to open in a new tab.
trailingIcon trailing-icon boolean false Whether to render the icon at the inline end of the label rather than the inline start.Note: Link buttons cannot have trailing icons.
hasIcon has-icon boolean false Whether to display the icon or not.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
type type string 'submit' A string indicating the form submission behavior of the element.- submit: The element submits the form. This is the default value if the attribute is not specified, or if it is dynamically changed to an empty or invalid value. - reset: The element resets the form. - button: The element does nothing.
value value string '' The value of the button. When combined with a name, the submitting button's name/value will be added to the form.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.

MdFilledTonalButton `<md-filled-tonal-button>`

Properties

Property Attribute Type Default Description
softDisabled soft-disabled boolean false Whether or not the button is "soft-disabled" (disabled but still focusable).Use this when a button needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
href href string '' The URL that the link button points to.
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the button is used as a link (href is set).
target target "" | "_blank" | "_parent" | "_self" | "_top" '' Where to display the linked href URL for a link button. Common options include _blank to open in a new tab.
trailingIcon trailing-icon boolean false Whether to render the icon at the inline end of the label rather than the inline start.Note: Link buttons cannot have trailing icons.
hasIcon has-icon boolean false Whether to display the icon or not.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
type type string 'submit' A string indicating the form submission behavior of the element.- submit: The element submits the form. This is the default value if the attribute is not specified, or if it is dynamically changed to an empty or invalid value. - reset: The element resets the form. - button: The element does nothing.
value value string '' The value of the button. When combined with a name, the submitting button's name/value will be added to the form.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.

MdOutlinedButton `<md-outlined-button>`

Properties

Property Attribute Type Default Description
softDisabled soft-disabled boolean false Whether or not the button is "soft-disabled" (disabled but still focusable).Use this when a button needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
href href string '' The URL that the link button points to.
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the button is used as a link (href is set).
target target "" | "_blank" | "_parent" | "_self" | "_top" '' Where to display the linked href URL for a link button. Common options include _blank to open in a new tab.
trailingIcon trailing-icon boolean false Whether to render the icon at the inline end of the label rather than the inline start.Note: Link buttons cannot have trailing icons.
hasIcon has-icon boolean false Whether to display the icon or not.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
type type string 'submit' A string indicating the form submission behavior of the element.- submit: The element submits the form. This is the default value if the attribute is not specified, or if it is dynamically changed to an empty or invalid value. - reset: The element resets the form. - button: The element does nothing.
value value string '' The value of the button. When combined with a name, the submitting button's name/value will be added to the form.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.

MdTextButton `<md-text-button>`

Properties

Property Attribute Type Default Description
softDisabled soft-disabled boolean false Whether or not the button is "soft-disabled" (disabled but still focusable).Use this when a button needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
href href string '' The URL that the link button points to.
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the button is used as a link (href is set).
target target "" | "_blank" | "_parent" | "_self" | "_top" '' Where to display the linked href URL for a link button. Common options include _blank to open in a new tab.
trailingIcon trailing-icon boolean false Whether to render the icon at the inline end of the label rather than the inline start.Note: Link buttons cannot have trailing icons.
hasIcon has-icon boolean false Whether to display the icon or not.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
type type string 'submit' A string indicating the form submission behavior of the element.- submit: The element submits the form. This is the default value if the attribute is not specified, or if it is dynamically changed to an empty or invalid value. - reset: The element resets the form. - button: The element does nothing.
value value string '' The value of the button. When combined with a name, the submitting button's name/value will be added to the form.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.

Components Checkbox (`docs/components/checkbox.md`)

Checkbox

This documentation is fully rendered on the
Material Web catalog.

Checkboxes allow users
to select one or more items from a set. Checkboxes can turn an option on or off.

There's one type of checkbox in Material. Use this selection control when the
user needs to select one or more options from a list.

Usage

Checkboxes may be standalone, pre-checked, or indeterminate.

html
<md-checkbox touch-target="wrapper"></md-checkbox>
<md-checkbox touch-target="wrapper" checked></md-checkbox>
<md-checkbox touch-target="wrapper" indeterminate></md-checkbox>

Label

Associate a label with a checkbox using the <label> element.

html
<label>
  <md-checkbox touch-target="wrapper"></md-checkbox>
  Checkbox one
</label>

<md-checkbox id="checkbox-two" touch-target="wrapper"></md-checkbox>
<label for="checkbox-two">Checkbox two</label>

Accessibility

Add an
aria-label
attribute to checkboxes without labels or checkboxes whose labels need to be
more descriptive.

html
<md-checkbox aria-label="Select all checkboxes"></md-checkbox>

<label>
  <md-checkbox aria-label="Agree to terms and conditions"></md-checkbox>
  Agree
</label>

Note: checkboxes are not automatically labelled by <label> elements and
always need an aria-label. See b/294081528.

Theming

Checkbox supports Material theming and can be customized
in terms of color and shape.

Tokens

Token Default value
--md-checkbox-outline-color --md-sys-color-on-surface-variant
--md-checkbox-selected-container-color --md-sys-color-primary
--md-checkbox-selected-icon-color --md-sys-color-on-primary
--md-checkbox-container-shape 2px

Example

html
<style>
  :root {
    /* System tokens */
    --md-sys-color-primary: #006a6a;
    --md-sys-color-on-primary: #ffffff;
    --md-sys-color-on-surface-variant: #3f4948;

    /* Component tokens */
    --md-checkbox-container-shape: 0px;
  }
</style>

<md-checkbox touch-target="wrapper"></md-checkbox>
<md-checkbox touch-target="wrapper" checked></md-checkbox>

API

MdCheckbox `<md-checkbox>`

Properties

Property Attribute Type Default Description
checked checked boolean false Whether or not the checkbox is selected.
indeterminate indeterminate boolean false Whether or not the checkbox is indeterminate.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes
required required boolean false When true, require the checkbox to be selected when participating in form submission.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#validation
value value string 'on' The value of the checkbox that is submitted with a form when selected.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.
validity ValidityState undefined Returns a ValidityState object that represents the validity states of the element.https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
validationMessage string undefined Returns a validation error message or an empty string if the element is valid.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
willValidate boolean undefined Returns whether an element will successfully validate based on forms validation rules and constraints.Disabled and readonly elements will not validate.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate

Methods

Method Parameters Returns Description
formResetCallback None void
formStateRestoreCallback state void
checkValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch an invalid event.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
reportValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch a cancelable invalid event. If not canceled, a the current validationMessage will be reported to the user.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
setCustomValidity error void Sets the element's constraint validation error message. When set to a non-empty string, validity.customError will be true and validationMessage will display the provided error.Use this method to customize error messages reported.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity

Events

Event Type Bubbles Composed Description
change Event Yes No The native change event on ``
input InputEvent Yes Yes The native input event on ``

Components Chip (`docs/components/chip.md`)

Chips

This documentation is fully rendered on the
Material Web catalog

Chips help people enter
information, make selections, filter content, or trigger actions.

While buttons are expected to appear consistently and with familiar calls to
action, chips should appear dynamically as a group of multiple interactive
elements.

Types

  1. Assist chip
  2. Filter chip
  3. Input chip
  4. Suggestion chip

Usage

Choose the type of chip based on its purpose and author.

  • Assist chips are common actions, such as adding an event to a calendar.
  • Filter chips are tags used to filter content, such as shopping
    categories.
  • Input chips are pieces of information entered by a user, such as event
    attendees.
  • Suggestion chips represent dynamic suggestions for user input, such as
    text message replies.
html
<md-chip-set>
  <md-assist-chip label="Assist"></md-assist-chip>
  <md-filter-chip label="Filter"></md-filter-chip>
  <md-input-chip label="Input"></md-input-chip>
  <md-suggestion-chip label="Suggestion"></md-suggestion-chip>
</md-chip-set>

Chip sets

Chips should always appear in a set. Chip sets are
toolbars
that can display any type of chip or other toolbar items.

html
<h3>New event</h3>
<md-chip-set>
  <md-filter-chip label="All day"></md-filter-chip>
  <md-assist-chip label="Add to calendar"></md-assist-chip>
  <md-assist-chip label="Set a reminder"></md-assist-chip>
</md-chip-set>

Icons

All chips may display an optional icon. Input chips can specify if an avatar
picture is displayed.

html
<md-chip-set>
  <md-assist-chip label="Add to calendar">
    <md-icon slot="icon">event</md-icon>
  </md-assist-chip>

  <md-input-chip label="Ping Qiang" avatar>
    <img slot="icon" src="...">
  </md-input-chip>
</md-chip-set>

Elevated

Assist, filter, and suggestion chips can be elevated if the placement requires
protection, such as on top of an image.

html
<div>
  <img src="...">
  <md-chip-set>
    <md-suggestion-chip label="Share" elevated></md-suggestion-chip>
    <md-suggestion-chip label="Favorite" elevated></md-suggestion-chip>
  </md-chip-set>
</div>

Accessibility

Add an
aria-label
attribute to chip sets or reference a label with
aria-labelledby.
Add an aria-label to chips whose labels need to be more descriptive.

html
<h3 id="dates-label">Dates</h3>
<md-chip-set aria-labelledby="dates-label">
  <md-filter-chip label="Mon" aria-label="Monday"></md-filter-chip>
  <md-filter-chip label="Tue" aria-label="Tuesday"></md-filter-chip>
  <md-filter-chip label="Wed" aria-label="Wednesday"></md-filter-chip>
</md-chip-set>

Focusable and disabled

By default, disabled chips are not focusable with the keyboard, while
"soft-disabled" chips are. Some use cases encourage focusability of disabled
toolbar items to increase their discoverability.

See the
ARIA guidelines on focusability of disabled controls
for guidance on when this is recommended.

html
<md-chip-set aria-label="Actions">
  
  <md-assist-chip label="Copy" soft-disabled></md-assist-chip>
  <md-assist-chip label="Paste" soft-disabled></md-assist-chip>
</md-chip-set>
<md-outlined-text-field type="textarea"></md-outlined-text-field>

Assist chip

Assist chips
represent smart or automated actions that can span multiple apps, such as
opening a calendar event from the home screen.

Assist chips function as though the user asked an assistant to complete the
action. They should appear dynamically and contextually in a UI.

html
<h3>A restaraunt location</h3>
<md-chip-set>
  <md-assist-chip label="Add to my itinerary">
    <md-icon slot="icon">calendar</md-icon>
  </md-assist-chip>
  <md-assist-chip label="12 mins from hotel">
    <md-icon slot="icon">map</md-icon>
  </md-assist-chip>
</md-chip-set>

Filter chip

Filter chips
use tags or descriptive words to filter content. They can be a good alternative
to toggle buttons or checkboxes.

html
<h3>Choose where to share</h3>
<md-chip-set>
  <md-filter-chip label="Docs"></md-filter-chip>
  <md-filter-chip label="Slides" selected></md-filter-chip>
  <md-filter-chip label="Sheets" selected></md-filter-chip>
  <md-filter-chip label="Images"></md-filter-chip>
</md-chip-set>

Removable

Filter chips can optionally be removable from the chip set. Removable chips have
a trailing remove icon.

html
<h3>Colors</h3>
<md-chip-set>
  <md-filter-chip label="Red" removable selected></md-filter-chip>
  <md-filter-chip label="Yellow" removable></md-filter-chip>
  <md-filter-chip label="Blue" removable></md-filter-chip>
  <md-filter-chip label="Green" removable></md-filter-chip>
</md-chip-set>

Input chip

Input chips
represent discrete pieces of information entered by a user, such as Gmail
contacts or filter options within a search field.

Input chips whose icons are user images may add the avatar attribute to
display the image in a larger circle.

html
<md-outlined-text-field label="Attendees" type="email"></md-outlined-text-field>

<md-chip-set>
  <md-input-chip label="Ping Qiang" avatar>
    <img slot="icon" src="...">
  </md-input-chip>
  <md-input-chip label="Thea Schröder" avatar>
    <img slot="icon" src="...">
  </md-input-chip>
</md-chip-set>

Remove-only

All input chips are removable. If an input chip does not have an action
associated with clicking on it, it may be marked as remove-only.

html
<h3>Favorite movies</h3>
<md-chip-set>
  <md-input-chip label="Star Wars" remove-only></md-input-chip>
  <md-input-chip label="Star Trek" remove-only></md-input-chip>
</md-chip-set>

Suggestion chip

Suggestion chips
help narrow a user’s intent by presenting dynamically generated suggestions,
such as possible responses or search filters.

html
<h3>Suggested reply</h3>
<md-chip-set>
  <md-suggestion-chip label="I agree"></md-suggestion-chip>
  <md-suggestion-chip label="Looks good to me"></md-suggestion-chip>
  <md-suggestion-chip label="Thank you"></md-suggestion-chip>
</md-chip-set>

Theming

Chips support Material theming and can be customized in
terms of color, typography, and shape.

Assist chip tokens

Token Default value
--md-assist-chip-outline-color --md-sys-color-outline
--md-assist-chip-container-shape --md-sys-shape-corner-small
--md-assist-chip-icon-size 18px
--md-assist-chip-label-text-color --md-sys-color-on-surface
--md-assist-chip-label-text-font --md-sys-typescale-label-large-font

Assist chip example

html
<style>
:root {
  --md-assist-chip-container-shape: 0px;
  --md-assist-chip-label-text-font: system-ui;
  --md-sys-color-outline: #6F7979;
  --md-sys-color-on-surface: #191C1C;
}
</style>

<md-assist-chip label="Assist"></md-assist-chip>

Filter chip tokens

Token Default value
--md-filter-chip-selected-container-color --md-sys-color-secondary-container
--md-filter-chip-outline-color --md-sys-color-outline
--md-filter-chip-container-shape --md-sys-shape-corner-small
--md-filter-chip-icon-size 18px
--md-filter-chip-label-text-color --md-sys-color-on-surface
--md-filter-chip-label-text-font --md-sys-typescale-label-large-font

Filter chip example

html
<style>
:root {
  --md-filter-chip-container-shape: 0px;
  --md-filter-chip-label-text-font: system-ui;
  --md-sys-color-outline: #6f7979;
  --md-sys-color-on-surface: #191c1c;
  --md-sys-color-secondary-container: #cce8e7;
}
</style>

<md-filter-chip label="Filter"></md-filter-chip>

Input chip tokens

Token Default value
--md-input-chip-outline-color --md-sys-color-outline
--md-input-chip-container-shape --md-sys-shape-corner-small
--md-input-chip-icon-size 18px
--md-input-chip-label-text-color --md-sys-color-on-surface
--md-input-chip-label-text-font --md-sys-typescale-label-large-font

Input chip example

html
<style>
:root {
  --md-input-chip-container-shape: 0px;
  --md-input-chip-label-text-font: system-ui;
  --md-sys-color-outline: #6f7979;
  --md-sys-color-on-surface: #191c1c;
}
</style>

<md-input-chip label="Input"></md-input-chip>

Suggestion chip tokens

Token Default value
--md-suggestion-chip-outline-color --md-sys-color-outline
--md-suggestion-chip-container-shape --md-sys-shape-corner-small
--md-suggestion-chip-icon-size 18px
--md-suggestion-chip-label-text-color --md-sys-color-on-surface
--md-suggestion-chip-label-text-font --md-sys-typescale-label-large-font

Suggestion chip example

html
<style>
:root {
  --md-suggestion-chip-container-shape: 0px;
  --md-suggestion-chip-label-text-font: system-ui;
  --md-sys-color-outline: #6f7979;
  --md-sys-color-on-surface: #191c1c;
}
</style>

<md-suggestion-chip label="Suggestion"></md-suggestion-chip>

API

MdChipSet `<md-chip-set>`

Properties

Property Attribute Type Default Description
chips Chip[] undefined

MdAssistChip `<md-assist-chip>`

Properties

Property Attribute Type Default Description
elevated elevated boolean false
href href string ''
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the chip is used as a link (href is set).
target target "" | "_blank" | "_parent" | "_self" | "_top" ''
disabled disabled boolean false Whether or not the chip is disabled.Disabled chips are not focusable, unless always-focusable is set.
softDisabled soft-disabled boolean false Whether or not the chip is "soft-disabled" (disabled but still focusable).Use this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
alwaysFocusable always-focusable boolean false When true, allow disabled chips to be focused with arrow keys.Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
label label string '' The label of the chip.
hasIcon has-icon boolean false Only needed for SSR.Add this attribute when a chip has a slot="icon" to avoid a Flash Of Unstyled Content.

Events

Event Type Bubbles Composed Description
update-focus Event Yes No Dispatched when disabled is toggled.

MdFilterChip `<md-filter-chip>`

Properties

Property Attribute Type Default Description
elevated elevated boolean false
removable removable boolean false
selected selected boolean false
hasSelectedIcon has-selected-icon boolean false Only needed for SSR.Add this attribute when a filter chip has a slot="selected-icon" to avoid a Flash Of Unstyled Content.
disabled disabled boolean false Whether or not the chip is disabled.Disabled chips are not focusable, unless always-focusable is set.
softDisabled soft-disabled boolean false Whether or not the chip is "soft-disabled" (disabled but still focusable).Use this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
alwaysFocusable always-focusable boolean false When true, allow disabled chips to be focused with arrow keys.Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
label label string '' The label of the chip.
hasIcon has-icon boolean false Only needed for SSR.Add this attribute when a chip has a slot="icon" to avoid a Flash Of Unstyled Content.
handleTrailingActionFocus () => void undefined
ariaLabelRemove string undefined

Events

Event Type Bubbles Composed Description
remove Event No No Dispatched when the remove button is clicked.
update-focus Event Yes No Dispatched when disabled is toggled.

MdInputChip `<md-input-chip>`

Properties

Property Attribute Type Default Description
avatar avatar boolean false
href href string ''
target target "" | "_blank" | "_parent" | "_self" | "_top" ''
removeOnly remove-only boolean false
selected selected boolean false
disabled disabled boolean false Whether or not the chip is disabled.Disabled chips are not focusable, unless always-focusable is set.
softDisabled soft-disabled boolean false Whether or not the chip is "soft-disabled" (disabled but still focusable).Use this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
alwaysFocusable always-focusable boolean false When true, allow disabled chips to be focused with arrow keys.Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
label label string '' The label of the chip.
hasIcon has-icon boolean false Only needed for SSR.Add this attribute when a chip has a slot="icon" to avoid a Flash Of Unstyled Content.
handleTrailingActionFocus () => void undefined
ariaLabelRemove string undefined

Events

Event Type Bubbles Composed Description
remove Event No No Dispatched when the remove button is clicked.
update-focus Event Yes No Dispatched when disabled is toggled.

MdSuggestionChip `<md-suggestion-chip>`

Properties

Property Attribute Type Default Description
elevated elevated boolean false
href href string ''
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the chip is used as a link (href is set).
target target "" | "_blank" | "_parent" | "_self" | "_top" ''
disabled disabled boolean false Whether or not the chip is disabled.Disabled chips are not focusable, unless always-focusable is set.
softDisabled soft-disabled boolean false Whether or not the chip is "soft-disabled" (disabled but still focusable).Use this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
alwaysFocusable always-focusable boolean false When true, allow disabled chips to be focused with arrow keys.Add this when a chip needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
label label string '' The label of the chip.
hasIcon has-icon boolean false Only needed for SSR.Add this attribute when a chip has a slot="icon" to avoid a Flash Of Unstyled Content.

Events

Event Type Bubbles Composed Description
update-focus Event Yes No Dispatched when disabled is toggled.

Components Dialog (`docs/components/dialog.md`)

Dialogs

This documentation is fully rendered on the
Material Web catalog

Dialogs provide
important prompts in a user flow.

Usage

Dialogs behave like
<dialog>
elements, and can be closed with a <form method="dialog"> element.

Dialogs have three optional sections: the headline title, the main content, and
action buttons.

html
<md-dialog>
  <div slot="headline">
    Dialog title
  </div>
  <form slot="content" id="form-id" method="dialog">
    A simple dialog with free-form content.
  </form>
  <div slot="actions">
    <md-text-button form="form-id">Ok</md-text-button>
  </div>
</md-dialog>

Tip: use margin, height, and width CSS properties to control the
dialog's size and position.

Opening and closing

Dialogs are opened and closed by setting the open attribute or property.

html
<md-dialog open>
  <div slot="content">
    A dialog that is opened by default.
  </div>
</md-dialog>

Dialogs are also opened and closed by calling dialog.show() and
dialog.close().

Both return a Promise that resolves after the dialog's animation finishes.

ts
closeButton.addEventListener('click', async () => {
  await dialog.close();
});

Return value

A button's value attribute will set the dialog's returnValue property to
identify which button closed it.

html
<md-dialog open>
  <form slot="content" id="form-id" method="dialog">...</form>
  <div slot="actions">
    <md-text-button form="form-id" value="cancel">Cancel</md-text-button>
    <md-text-button form="form-id" value="ok">Ok</md-text-button>
  </div>
</md-dialog>
ts
dialog.addEventListener('close', () => {
  const cancelClicked = dialog.returnValue === 'cancel';
  const okClicked = dialog.returnValue === 'ok';
});

Accessibility

Dialogs are labelled by their headlines. Add an
aria-label
attribute to dialogs without a headline.

html
<md-dialog aria-label="Error message">
  <div slot="content">An error occurred, details ...</div>
</md-dialog>

Alerts

Add a
type="alert"
attribute to dialogs that need to communicate an important message and require a
user's response.

Common examples include error messages that require confirmation and other
action confirmation prompts.

html
<md-dialog type="alert">
  <div slot="headline">Confirm deletion</div>
  <form slot="content" id="form-id" method="dialog">
    Are you sure you wish to delete this item?
  </form>
  <div slot="actions">
    <md-text-button form="form-id" value="cancel">Cancel</md-text-button>
    <md-text-button form="form-id" value="delete">Delete</md-text-button>
  </div>
</md-dialog>

Theming

Dialogs supports Material theming and can be customized
in terms of color, typography, and shape.

Tokens

Token Default value
--md-dialog-container-color --md-sys-color-surface-container-high
--md-dialog-headline-color --md-sys-color-on-surface
--md-dialog-headline-font --md-sys-typescale-headline-small-font
--md-dialog-supporting-text-color --md-sys-color-on-surface-variant
--md-dialog-supporting-text-font --md-sys-typescale-body-medium-font

Example

html
<style>
:root {
  /* System tokens */
  --md-sys-color-surface-container-highest: #dde4e3;
  --md-sys-color-on-surface: #161d1d;
  --md-sys-color-on-surface-variant: #3f4948;
  --md-sys-typescale-body-medium: system-ui 16px/24px;
  --md-sys-typescale-headline-small: system-ui 24px/32px;

  /* Component tokens */
  --md-dialog-container-shape: 0px;
}
</style>

<md-dialog>
  <div slot="headline">Title</div>
  <div slot="content">Dialog content</div>
</md-dialog>

API

MdDialog `<md-dialog>`

Properties

Property Attribute Type Default Description
quick quick boolean false Skips the opening and closing animations.
returnValue string '' Gets or sets the dialog's return value, usually to indicate which button a user pressed to close it.https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/returnValue
type type string undefined The type of dialog for accessibility. Set this to alert to announce a dialog as an alert dialog.
noFocusTrap no-focus-trap boolean false Disables focus trapping, which by default keeps keyboard Tab navigation within the dialog.When disabled, after focusing the last element of a dialog, pressing Tab again will release focus from the window back to the browser (such as the URL bar).Focus trapping is recommended for accessibility, and should not typically be disabled. Only turn this off if the use case of a dialog is more accessible without focus trapping.
open open boolean undefined
getOpenAnimation () => DialogAnimation function { ... } Gets the opening animation for a dialog. Set to a new function to customize the animation.
getCloseAnimation () => DialogAnimation function { ... } Gets the closing animation for a dialog. Set to a new function to customize the animation.

Methods

Method Parameters Returns Description
show None Promise<void> Opens the dialog and fires a cancelable open event. After a dialog's animation, an opened event is fired.Add an autofocus attribute to a child of the dialog that should receive focus after opening.
close returnValue Promise<void> Closes the dialog and fires a cancelable close event. After a dialog's animation, a closed event is fired.

Events

Event Type Bubbles Composed Description
open Event No No Dispatched when the dialog is opening before any animations.
opened Event No No Dispatched when the dialog has opened after any animations.
close Event No No Dispatched when the dialog is closing before any animations.
closed Event No No Dispatched when the dialog has closed after any animations.
cancel Event No No Dispatched when the dialog has been canceled by clicking on the scrim or pressing Escape.

Components Divider (`docs/components/divider.md`)

Divider

A divider is a thin line
that groups content in lists and containers.

Dividers can reinforce tapability, such as when used to separate list items or
define tappable regions in an accordion.

Usage

Use full width dividers to separate larger sections of unrelated content.

html
<section>
  <p>Lorem ipsum...</p>
  <md-divider></md-divider>
  <p>Lorem ipsum...</p>
</section>

Inset dividers

Use inset dividers to separate related content within a section.

html
<section>
  <p>Material 2</p>
  <md-divider inset></md-divider>
  <p>Material 3</p>
</section>

Inset dividers are equally indented from both sides of the screen by default.
Use inset-start or inset-end to change this.

html
<section>
  <p>Material 2</p>
  <md-divider inset-start></md-divider>
  <p>Material 3</p>
</section>

Accessibility

Dividers are decorative by default and not announced by assistive technology.

Add a
role="separator"
attribute to non-decorative dividers that should be announced.

html
<ul>
  <li>Item one</li>
  <md-divider inset></md-divider>
  <li>Item two</li>
  <md-divider role="separator"></md-divider>
  <li>Item three</li>
  <md-divider inset></md-divider>
  <li>Item four</li>
</ul>

Theming

Divider supports theming and can be customized with CSS
custom property tokens.

Tokens

Token Default value
--md-divider-color --md-sys-color-outline-variant
--md-divider-thickness 1px

Example

html
<style>
:root {
  --md-sys-color-outline-variant: #BEC9C8;
  --md-divider-thickness: 2px;
}
</style>

<section>
  <p>Lorem ipsum...</p>
  <md-divider></md-divider>
  <p>Lorem ipsum...</p>
</section>

API

MdDivider `<md-divider>`

Properties

Property Attribute Type Default Description
inset inset boolean false Indents the divider with equal padding on both sides.
insetStart inset-start boolean false Indents the divider with padding on the leading side.
insetEnd inset-end boolean false Indents the divider with padding on the trailing side.

Components Elevation (`docs/components/elevation.md`)

Elevation

Elevation is the relative
distance between two surfaces along the z-axis.

Material's elevation system is deliberately limited to just a handful of levels.
This creative constraint means you need to make thoughtful decisions about your
UI’s elevation story.

Usage

Elevation can be set from 0 to 5 using the --md-elevation-level CSS custom
property. The elevation will automatically fill the nearest position: relative
element's size and shape.

html
<style>
  .surface {
    position: relative;
    border-radius: 16px;
    height: 64px;
    width: 64px;

    --md-elevation-level: 3;
  }
</style>
<div class="surface">
  <md-elevation></md-elevation>
  
</div>

Animation

Shadows may be animated between levels by adding transition-duration and
transition-easing-function CSS properties.

A rounded square with a drop shadow beneath it. After a moment, the squarelowers into the background and the shadow disappears, thenrepeats.

html
<style>
  .surface {
    /* ... */
    transition-duration: 250ms;
    transition-timing-function: ease-in-out;

    --md-elevation-level: 3;
  }

  .surface:active {
    --md-elevation-level: 0;
  }
</style>
<div class="surface">
  <md-elevation></md-elevation>
  
</div>

Accessibility

Elevation is a visual component and does not have accessibility concerns.

Theming

Elevation supports Material theming and can be
customized in terms of color.

Tokens

Token Default value
--md-elevation-level 0
--md-elevation-shadow-color --md-sys-color-shadow

Example

html
<style>
  .surface {
    position: relative;
    border-radius: 16px;
    height: 64px;
    width: 64px;
  }

  :root {
    --md-elevation-level: 5;
    --md-sys-color-shadow: #006A6A;
  }
</style>
<div class="surface">
  <md-elevation></md-elevation>
  
</div>

Components Fab (`docs/components/fab.md`)

Floating action buttons (FAB)

This documentation is fully rendered on the
Material Web catalog.

FAB
represents the most important action on a screen. It puts key actions within
reach.

Extended FABs help people take
primary actions. They're wider than FABs to accommodate a text label and larger
target area.

Types

  1. FAB
  2. Small FAB
  3. Large FAB

Extended FAB

Usage

FABs should have an icon, such as a font md-icon, an svg, or an img.

html
<md-fab aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>

Lowered

FABs can be set to a lower elevation with the lowered attribute.

html
<md-fab lowered aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>

Accessibility

Icon-only FABs must include an aria-label that describes its action. Otherwise
if aria-label is not provided, the FAB will default to announcing its visible
contents.

html
<md-fab aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>

Extended FABs use their label for accessibility. Add an aria-label for
additional context if needed. By supplying the label attribute, the extended
FAB will make sure that the icon is not announced.

html
<md-fab label="Edit" aria-label="Edit Comment">
  <md-icon slot="icon">edit</md-icon>
</md-fab>

FAB

FABs should display a clear and understandable icon.

html
<md-fab aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>

Extended

FABs may be extended with a label for additional emphasis. Extended FABs can
omit their icon.

html
<md-fab label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>

Without icon

Extended FABs are the only FABs that can be used without an icon.

html
<md-fab label="Reroute"></md-fab>

Colors

FAB colors may be changed with the variant attribute. It can be set to
"surface" (default), "primary", "secondary", or "tertiary".

Three fabs with edit icons next to each other but the first is primarycolored, second is secondary, and the last is tertiarycolored.

html
<md-fab variant="primary" aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>
<md-fab variant="secondary" aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>
<md-fab variant="tertiary" aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>

Sizes

FABs may be small, medium (default), or large by setting the size attribute.
Small FABs can optionally further reduce their touch target.

Four surface fabs side by side with edit icons of visual size size small,small, medium, and large

html
<md-fab size="small" touch-target="none" aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>
<md-fab size="small" aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>
<md-fab aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>
<md-fab size="large" aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>

Branded FAB

Branded FABs use a brightly colored logo for their icon. Unlike FAB,
branded FABs do not have color variants.

html
<md-branded-fab size="small" aria-label="Add">
  <svg slot="icon" viewBox="0 0 36 36">
    <path fill="#34A853" d="M16 16v14h4V20z"></path>
    <path fill="#4285F4" d="M30 16H20l-4 4h14z"></path>
    <path fill="#FBBC05" d="M6 16v4h10l4-4z"></path>
    <path fill="#EA4335" d="M20 16V6h-4v14z"></path>
    <path fill="none" d="M0 0h36v36H0z"></path>
  </svg>
</md-branded-fab>

Extended

Branded FABs may be extended with a label for additional emphasis. Unlike
FAB, branded FABs should always display their logo icon.

An extended branded fab with a google-colored plus icon and the visible textAdd

html
<md-branded-fab label="Add">
  <svg slot="icon" viewBox="0 0 36 36">
    <path fill="#34A853" d="M16 16v14h4V20z"></path>
    <path fill="#4285F4" d="M30 16H20l-4 4h14z"></path>
    <path fill="#FBBC05" d="M6 16v4h10l4-4z"></path>
    <path fill="#EA4335" d="M20 16V6h-4v14z"></path>
    <path fill="none" d="M0 0h36v36H0z"></path>
  </svg>
</md-branded-fab>

Sizes

Branded FABs may be medium (default) or large by setting the size attribute.

Two branded FABs next to each other with a google-branded plus icon. A mediumsized one and a large one.

html
<md-branded-fab aria-label="Add">
  <svg slot="icon" viewBox="0 0 36 36">
    <path fill="#34A853" d="M16 16v14h4V20z"></path>
    <path fill="#4285F4" d="M30 16H20l-4 4h14z"></path>
    <path fill="#FBBC05" d="M6 16v4h10l4-4z"></path>
    <path fill="#EA4335" d="M20 16V6h-4v14z"></path>
    <path fill="none" d="M0 0h36v36H0z"></path>
  </svg>
</md-branded-fab>
<md-branded-fab size="large" aria-label="Add">
  <svg slot="icon" viewBox="0 0 36 36">
    <path fill="#34A853" d="M16 16v14h4V20z"></path>
    <path fill="#4285F4" d="M30 16H20l-4 4h14z"></path>
    <path fill="#FBBC05" d="M6 16v4h10l4-4z"></path>
    <path fill="#EA4335" d="M20 16V6h-4v14z"></path>
    <path fill="none" d="M0 0h36v36H0z"></path>
  </svg>
</md-branded-fab>

Theming

FAB supports Material theming and can be customized in
terms of color, typography, and shape.

FAB tokens

Token Default value
--md-fab-container-color --md-sys-color-surface-container-high
--md-fab-lowered-container-color --md-sys-color-surface-container-low
--md-fab-container-shape --md-sys-shape-corner-large
--md-fab-icon-color --md-sys-color-primary
--md-fab-icon-size 24px

FAB example

html
<style>
  :root {
    --md-sys-color-surface-container-high: #e3e9e9;
    --md-sys-color-primary: #006a6a;
    --md-fab-container-shape: 0px;
    --md-fab-icon-size: 36px;
    background-color: #f4fbfa;
  }
</style>
<md-fab aria-label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>

Sizes tokens

Token Default value
--md-fab-small-container-shape --md-sys-shape-corner-medium
--md-fab-small-icon-size 24px
--md-fab-large-container-shape --md-sys-shape-corner-extra-large
--md-fab-large-icon-size 36px

Extended FAB tokens

Token Default value
--md-fab-label-text-font --md-sys-typescale-label-large-font

Extended FAB example

html
<style>
  :root {
    --md-sys-color-surface-container-high: #e3e9e9;
    --md-sys-color-on-surface: #161d1d;
    --md-sys-color-primary: #006a6a;
    --md-fab-container-shape: 0px;
    --md-fab-icon-size: 36px;
    background-color: #f4fbfa;
  }
</style>
<md-fab label="Edit">
  <md-icon slot="icon">edit</md-icon>
</md-fab>

Branded FAB tokens

Token Default value
--md-fab-branded-container-color --md-sys-color-surface-container-high
--md-fab-branded-container-shape --md-sys-shape-corner-large
--md-fab-branded-icon-size 36px
--md-fab-branded-label-text-font --md-sys-typescale-label-large-font

Branded FAB example

Image of two branded fabs, one regular, one extended with the visible labelAdd with a different theme applied

html
<style>
  :root {
    --md-sys-color-surface-container-high: #e3e9e9;
    --md-sys-color-on-surface: #161d1d;
    --md-fab-branded-icon-size: 48px;
    --md-fab-branded-container-shape: 0px;
    background-color: #f4fbfa;
  }
</style>
<md-branded-fab size="small" aria-label="Add">
  <svg slot="icon" viewBox="0 0 36 36">
    <path fill="#34A853" d="M16 16v14h4V20z"></path>
    <path fill="#4285F4" d="M30 16H20l-4 4h14z"></path>
    <path fill="#FBBC05" d="M6 16v4h10l4-4z"></path>
    <path fill="#EA4335" d="M20 16V6h-4v14z"></path>
    <path fill="none" d="M0 0h36v36H0z"></path>
  </svg>
</md-branded-fab>
<md-branded-fab size="small" label="Add">
  <svg slot="icon" viewBox="0 0 36 36">
    <path fill="#34A853" d="M16 16v14h4V20z"></path>
    <path fill="#4285F4" d="M30 16H20l-4 4h14z"></path>
    <path fill="#FBBC05" d="M6 16v4h10l4-4z"></path>
    <path fill="#EA4335" d="M20 16V6h-4v14z"></path>
    <path fill="none" d="M0 0h36v36H0z"></path>
  </svg>
</md-branded-fab>

API

MdFab `<md-fab>`

Properties

Property Attribute Type Default Description
variant variant FabVariant 'surface' The FAB color variant to render.
size size FabSize 'medium' The size of the FAB.NOTE: Branded FABs cannot be sized to small, and Extended FABs do not have different sizes.
label label string '' The text to display on the FAB.
lowered lowered boolean false Lowers the FAB's elevation.

MdBrandedFab `<md-branded-fab>`

Properties

Property Attribute Type Default Description
variant variant FabVariant 'surface' The FAB color variant to render.
size size FabSize 'medium' The size of the FAB.NOTE: Branded FABs cannot be sized to small, and Extended FABs do not have different sizes.
label label string '' The text to display on the FAB.
lowered lowered boolean false Lowers the FAB's elevation.

Methods

Method Parameters Returns Description
getRenderClasses None { primary: boolean; secondary: boolean; tertiary: boolean; small: boolean; lowered: boolean; large: boolean; extended: boolean; }

Components Focus Ring (`docs/components/focus-ring.md`)

Focus ring

Focus rings are accessible outlines for components to show keyboard focus.

Focus rings follow the same heuristics as
:focus-visible
to determine when they are visible.

Usage

Focus rings display on keyboard navigation. They may be attached to a control in
one of three ways.

  1. Attached to the parent element

    html
    <button style="position: relative">
  <md-focus-ring style="--md-focus-ring-shape: 8px"></md-focus-ring>
</button>

  2. Attached to a referenced element

    html
    <div style="position: relative">
  <md-focus-ring for="control" style="--md-focus-ring-shape: 8px"></md-focus-ring>
  <input id="control">
</div>

  3. Attached imperatively

    html
    <div style="position: relative">
  <md-focus-ring id="ring" style="--md-focus-ring-shape: 8px"></md-focus-ring>
  <button id="ring-control"></button>
</div>
<script>
  const focusRing = document.querySelector('#ring');
  const control = document.querySelector('#ring-control');
  focusRing.attach(control);
</script>

Note: focus rings must be placed within a position: relative container.

Inward

Focus rings can be changed to animate inwards by adding an inward attribute.
This is useful for components like list items.

html
<button style="position: relative">
  <md-focus-ring inward style="--md-focus-ring-shape: 8px"></md-focus-ring>
</button>

Animation

The focus ring animation may be customized or disabled using CSS custom
properties.

html
<style>
  md-focus-ring {
    --md-focus-ring-duration: 0s; /* disabled animation */
  }
</style>

Accessibility

Focus rings are visual components and do not have assistive technology
requirements.

Theming

Focus rings supports Material theming and can be
customized in terms of color and shape.

Tokens

Token Default value
--md-focus-ring-color --md-sys-color-secondary
--md-focus-ring-shape --md-sys-shape-corner-full
--md-focus-ring-width 3px

Example

html
<style>
md-focus-ring {
  --md-focus-ring-shape: 0px;
  --md-focus-ring-width: 2px;
  --md-focus-ring-active-width: 4px;
  --md-sys-color-secondary: #4A6363;
}
</style>

<button>
  <md-focus-ring></md-focus-ring>
</button>

API

MdFocusRing `<md-focus-ring>`

Properties

Property Attribute Type Default Description
visible visible boolean false Makes the focus ring visible.
inward inward boolean false Makes the focus ring animate inwards instead of outwards.
htmlFor string undefined
control HTMLElement undefined

Methods

Method Parameters Returns Description
attach control void
detach None void

Events

Event Type Bubbles Composed Description
visibility-changed Event No No Fired whenever visible changes.

Components Icon Button (`docs/components/icon-button.md`)

Icon Buttons

This documentation is fully rendered on the
Material Web catalog.

Icon buttons help
people take supplementary actions with a single tap.

Types

")

  1. Icon Button
  2. Filled Icon Button
  3. Filled Tonal Icon Button
  4. Outlined Icon Button

Usage

Use icon buttons to display actions in a compact layout. Icon buttons can
represent opening actions such as opening an overflow menu or search, or
represent binary actions that can be toggled on and off, such as favorite or
bookmark.

Icon buttons can be grouped together or they can stand alone.

To use icons by name, see the Icon documentation for loading
the icon font.

html
<md-icon-button>
  <md-icon>check</md-icon>
</md-icon-button>
<md-filled-icon-button>
  <md-icon>check</md-icon>
</md-filled-icon-button>
<md-filled-tonal-icon-button>
  <md-icon>check</md-icon>
</md-filled-tonal-icon-button>
<md-outlined-icon-button>
  <md-icon>check</md-icon>
</md-outlined-icon-button>

Add an
href
and optionally a
target
attribute to turn the icon button into a link.

html
<md-icon-button href="https://google.com">
  <md-icon>check</md-icon>
</md-icon-button>

Toggle

Two rows of toggling icon buttons, the top row is unselected and the bottomrow isselected

Toggle icon buttons allow a single choice to be selected or deselected, such as
adding or removing something from favorites.

Add a second icon in the slot="selected" slot to change the icon when
selected. Toggle icon buttons can be pre-selected by adding the selected
attribute.

html
<div>
  <md-icon-button toggle>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-icon-button>
  <md-filled-icon-button toggle>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-filled-icon-button>
  <md-filled-tonal-icon-button toggle>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-filled-tonal-icon-button>
  <md-outlined-icon-button toggle>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-outlined-icon-button>
</div>
<div>
  <md-icon-button toggle selected>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-icon-button>
  <md-filled-icon-button toggle selected>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-filled-icon-button>
  <md-filled-tonal-icon-button toggle selected>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-filled-tonal-icon-button>
  <md-outlined-icon-button toggle selected>
    <md-icon>close</md-icon>
    <md-icon slot="selected">check</md-icon>
  </md-outlined-icon-button>
</div>

Accessibility

Add an
aria-label
attribute to icon buttons whose labels need a more descriptive label.

html
<md-icon-button aria-label="Search for Contact">
  <md-icon>search</md-icon>
</md-icon-button>

Toggle

Add an aria-label-selected attribute to toggle buttons whose labels need a
more descriptive label when selected.

html
<md-icon-button toggle
  aria-label="Unselected"
  aria-label-selected="Selected">
  <md-icon>close</md-icon>
  <md-icon slot="selected">check</md-icon>
</md-icon-button>

Focusable and disabled

By default, disabled icon buttons are not focusable with the keyboard, while
"soft-disabled" icon buttons are. Some use cases encourage focusability of
disabled toolbar items to increase their discoverability.

See the
ARIA guidelines on focusability of disabled controls
for guidance on when this is recommended.

html
<div role="toolbar">
  <md-icon-button aria-label="Copy">
    <md-icon>copy</md-icon>
  </md-icon-button>
  <md-icon-button aria-label="Cut">
    <md-icon>cut</md-icon>
  </md-icon-button>
  
  <md-icon-button aria-label="Paste" soft-disabled>
    <md-icon>paste</md-icon>
  </md-icon-button>
</div>

Icon Button

Standard icon buttons do not have a background or outline, and have the lowest
emphasis of the icon buttons.

html
<md-icon-button>
  <md-icon>check</md-icon>
</md-icon-button>

Filled Icon Button

Filled icon buttons have higher visual impact and are best for high emphasis
actions.

html
<md-filled-icon-button>
  <md-icon>check</md-icon>
</md-filled-icon-button>

Filled Tonal Icon Button

Filled tonal icon buttons are a middle ground between filled and outlined icon
buttons. They're useful in contexts where the button requires slightly more
emphasis than an outline would give, such as a secondary action paired with a
high emphasis action.

html
<md-filled-tonal-icon-button>
  <md-icon>check</md-icon>
</md-filled-tonal-icon-button>

Outlined Icon Button

Outlined icon buttons are medium-emphasis buttons. They're useful when an icon
button needs more emphasis than a standard icon button but less than a filled or
filled tonal icon button.

html
<md-outlined-icon-button>
  <md-icon>check</md-icon>
</md-outlined-icon-button>

Theming

Icon Button supports Material theming and can be
customized in terms of color, and shape.

Icon Button tokens

Token Default value
--md-icon-button-icon-color --md-sys-color-on-surface-variant
--md-icon-button-state-layer-shape --md-sys-shape-corner-full
--md-icon-button-icon-size 24px

Icon Button example

html
<style>
:root {
  --md-icon-button-icon-size: 32px;
  --md-sys-color-on-surface-variant: #dc362e;
  background-color: #fff8f6;
}
</style>

<md-icon-button>
  <md-icon>check</md-icon>
</md-icon-button>

Filled Icon Button tokens

Token Default value
--md-filled-icon-button-selected-container-color --md-sys-color-primary
--md-filled-icon-button-container-shape --md-sys-shape-corner-full
--md-filled-icon-button-container-width 40px
--md-filled-icon-button-container-height 40px
--md-filled-icon-button-icon-size 24px

Filled Icon Button example

html
<style>
:root {
  --md-filled-icon-button-container-width: 80px;
  --md-filled-icon-button-container-height: 80px;
  --md-filled-icon-button-icon-size: 40px;
  --md-filled-icon-button-container-shape: 0px;
  --md-sys-color-primary: #dc362e;
  background-color: #fff8f6;
}
</style>
<md-filled-icon-button>
  <md-icon>check</md-icon>
</md-filled-icon-button>

Filled Tonal Icon Button tokens

Token Default value
--md-filled-tonal-icon-button-selected-container-color --md-sys-color-secondary-container
--md-filled-tonal-icon-button-container-shape --md-sys-shape-corner-full
--md-filled-tonal-icon-button-container-width 40px
--md-filled-tonal-icon-button-container-height 40px
--md-filled-tonal-icon-button-icon-size 24px

Filled Tonal Icon Button example

html
<style>
:root {
  --md-filled-tonal-icon-button-container-width: 80px;
  --md-filled-tonal-icon-button-container-height: 80px;
  --md-filled-tonal-icon-button-container-shape: 0px;
  --md-filled-tonal-icon-button-icon-size: 40px;
  --md-sys-color-secondary-container: #006A6A;
}
</style>
<md-filled-tonal-icon-button>
  <md-icon>check</md-icon>
</md-filled-tonal-icon-button>

Outlined Icon Button tokens

Token Default value
--md-outlined-icon-button-outline-color --md-sys-color-outline
--md-outlined-icon-button-outline-width 1px
--md-outlined-icon-button-container-shape --md-sys-shape-corner-full
--md-outlined-icon-button-container-width 40px
--md-outlined-icon-button-container-height 40px
--md-outlined-icon-button-icon-size 24px

Outlined Icon Button example

html
<style>
:root {
  --md-outlined-icon-button-container-width: 80px;
  --md-outlined-icon-button-container-height: 80px;
  --md-outlined-icon-button-container-shape: 0px;
  --md-outlined-icon-button-icon-size: 40px;
  --md-outlined-icon-button-outline-width: 4px;
  --md-sys-color-outline: #006A6A;
}
</style>
<md-outlined-icon-button>
  <md-icon>check</md-icon>
</md-outlined-icon-button>

API

MdIconButton `<md-icon-button>`

Properties

Property Attribute Type Default Description
softDisabled soft-disabled boolean false "Soft-disables" the icon button (disabled but still focusable).Use this when an icon button needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
flipIconInRtl flip-icon-in-rtl boolean false Flips the icon if it is in an RTL context at startup.
href href string '' Sets the underlying HTMLAnchorElement's href resource attribute.
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the icon button is used as a link (href is set).
target target "" | LinkTarget '' Sets the underlying HTMLAnchorElement's target attribute.
ariaLabelSelected aria-label-selected string '' The aria-label of the button when the button is toggleable and selected.
toggle toggle boolean false When true, the button will toggle between selected and unselected states
selected selected boolean false Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no slot="selected" icon is provided.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
type type string 'submit' A string indicating the form submission behavior of the element.- submit: The element submits the form. This is the default value if the attribute is not specified, or if it is dynamically changed to an empty or invalid value. - reset: The element resets the form. - button: The element does nothing.
value value string '' The value of the button. When combined with a name, the submitting button's name/value will be added to the form.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.

Events

Event Type Bubbles Composed Description
input InputEvent Yes Yes Dispatched when a toggle button toggles
change Event Yes No Dispatched when a toggle button toggles

MdFilledIconButton `<md-filled-icon-button>`

Properties

Property Attribute Type Default Description
softDisabled soft-disabled boolean false "Soft-disables" the icon button (disabled but still focusable).Use this when an icon button needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
flipIconInRtl flip-icon-in-rtl boolean false Flips the icon if it is in an RTL context at startup.
href href string '' Sets the underlying HTMLAnchorElement's href resource attribute.
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the icon button is used as a link (href is set).
target target "" | LinkTarget '' Sets the underlying HTMLAnchorElement's target attribute.
ariaLabelSelected aria-label-selected string '' The aria-label of the button when the button is toggleable and selected.
toggle toggle boolean false When true, the button will toggle between selected and unselected states
selected selected boolean false Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no slot="selected" icon is provided.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
type type string 'submit' A string indicating the form submission behavior of the element.- submit: The element submits the form. This is the default value if the attribute is not specified, or if it is dynamically changed to an empty or invalid value. - reset: The element resets the form. - button: The element does nothing.
value value string '' The value of the button. When combined with a name, the submitting button's name/value will be added to the form.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.

Events

Event Type Bubbles Composed Description
input InputEvent Yes Yes Dispatched when a toggle button toggles
change Event Yes No Dispatched when a toggle button toggles

MdFilledTonalIconButton `<md-filled-tonal-icon-button>`

Properties

Property Attribute Type Default Description
softDisabled soft-disabled boolean false "Soft-disables" the icon button (disabled but still focusable).Use this when an icon button needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
flipIconInRtl flip-icon-in-rtl boolean false Flips the icon if it is in an RTL context at startup.
href href string '' Sets the underlying HTMLAnchorElement's href resource attribute.
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the icon button is used as a link (href is set).
target target "" | LinkTarget '' Sets the underlying HTMLAnchorElement's target attribute.
ariaLabelSelected aria-label-selected string '' The aria-label of the button when the button is toggleable and selected.
toggle toggle boolean false When true, the button will toggle between selected and unselected states
selected selected boolean false Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no slot="selected" icon is provided.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
type type string 'submit' A string indicating the form submission behavior of the element.- submit: The element submits the form. This is the default value if the attribute is not specified, or if it is dynamically changed to an empty or invalid value. - reset: The element resets the form. - button: The element does nothing.
value value string '' The value of the button. When combined with a name, the submitting button's name/value will be added to the form.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.

Events

Event Type Bubbles Composed Description
input InputEvent Yes Yes Dispatched when a toggle button toggles
change Event Yes No Dispatched when a toggle button toggles

MdOutlinedIconButton `<md-outlined-icon-button>`

Properties

Property Attribute Type Default Description
softDisabled soft-disabled boolean false "Soft-disables" the icon button (disabled but still focusable).Use this when an icon button needs increased visibility when disabled. See https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls for more guidance on when this is needed.
flipIconInRtl flip-icon-in-rtl boolean false Flips the icon if it is in an RTL context at startup.
href href string '' Sets the underlying HTMLAnchorElement's href resource attribute.
download download string '' The filename to use when downloading the linked resource. If not specified, the browser will determine a filename. This is only applicable when the icon button is used as a link (href is set).
target target "" | LinkTarget '' Sets the underlying HTMLAnchorElement's target attribute.
ariaLabelSelected aria-label-selected string '' The aria-label of the button when the button is toggleable and selected.
toggle toggle boolean false When true, the button will toggle between selected and unselected states
selected selected boolean false Sets the selected state. When false, displays the default icon. When true, displays the selected icon, or the default icon If no slot="selected" icon is provided.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
type type string 'submit' A string indicating the form submission behavior of the element.- submit: The element submits the form. This is the default value if the attribute is not specified, or if it is dynamically changed to an empty or invalid value. - reset: The element resets the form. - button: The element does nothing.
value value string '' The value of the button. When combined with a name, the submitting button's name/value will be added to the form.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.

Events

Event Type Bubbles Composed Description
input InputEvent Yes Yes Dispatched when a toggle button toggles
change Event Yes No Dispatched when a toggle button toggles

Components Icon (`docs/components/icon.md`)

Icon

Icons can be used to
represent common actions. Material Symbols are a set of variable icon fonts
created at seven weights across three different styles.

Usage

Icons can be specified by name, unicode code point, or have an <svg> child
element.

html
<md-icon>settings</md-icon>
<md-icon>&#xe834</md-icon>
<md-icon><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48"><path d="M10 40V24H4L24 6l10 8.85V9h4v9.55L44 24h-6v16H26.5V28h-5v12Zm3-3h5.5V25h11v12H35V19.95l-11-10-11 10Zm5.5-12h11-11Zm1.25-5.5h8.5q0-1.65-1.275-2.725Q25.7 15.7 24 15.7q-1.7 0-2.975 1.075Q19.75 17.85 19.75 19.5Z"/></svg></md-icon>

The full range of icons can be found on the
Material Symbols font page.

Material Symbols icons are available in three styles: outlined, rounded,
and sharp.

In addition, Material Symbols have four adjustable stylistic variable font
attributes called axes. An axis is a typographic term referring to the attribute
of a symbol that can be altered to create visual variations.

Each style symbol contains four axes: weight, fill, grade, and
optical size.

The weight and optical size attributes are handled automatically, but the
fill and grade attributes are custom to the Material Symbols font, and must
be set with the
font-variation-settings
property.

Outlined

Outlined symbols use stroke and fill attributes for a light, clean style that
works well in dense UIs. The stroke weight of outlined icons can be adjusted to
complement or contrast the weight of your typography.

Load the font with

html
<link href="https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined" rel="stylesheet">

Rounded

Rounded symbols use a corner radius that pairs well with brands that use heavier
typography, curved logos, or circular elements to express their style.

Load the font with

html
<link href="https://fonts.googleapis.com/icon?family=Material+Symbols+Rounded" rel="stylesheet">

To use Rounded icons, set --md-icon-font to 'Material Symbols Rounded'.

Sharp

Sharp symbols display corners with straight edges, for a crisp style that
remains legible even at smaller scales. These rectangular shapes can support
brand styles that aren’t well-reflected by rounded shapes.

Load the font with

html
<link href="https://fonts.googleapis.com/icon?family=Material+Symbols+Sharp" rel="stylesheet">

To use Sharp icons, set font-family to 'Material Symbols Sharp'.

Fill

Filled Icons gives you the ability to transition from a more outlined style to a
reversed or more filled style.

A fill attribute can be used to convey a state of transition, such as unfilled
and filled states. Values range from 0 to 1, with 1 being completely
filled. Along with weight, fill is a primary attribute that impacts the overall
look of a symbol.

All styles of Material Symbols can be filled by setting
font-variation-settings to 'FILL' 1.

Accessibility

Icons are mostly intended to be used inside of other components that have
accessibility settings.

If used on their own, Icons should be given an accessible name if they are
focusable. If you use icons by name, they will be announced by screen readers
without any extra steps.

If using codepoints, wrap the codepoint in a `` with an
aria-label
attribute.

html
<md-icon tabindex="-1"><span aria-label="home">&#xe88a</span></md-icon>

If using SVG icons, add an aria-label attribute to the SVG element.

html
<md-icon tabindex="-1"><svg aria-label="paper airplane" viewBox="0 0 48 48"><path d="M6 40V8l38 16Zm3-4.65L36.2 24 9 12.5v8.4L21.1 24 9 27Zm0 0V12.5 27Z"/></svg></md-icon>

Theming

Tokens

Token Default value
--md-icon-font 'Material Symbols Outlined'
--md-icon-size 24px

Example

html
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,[email protected],100..700,0..1" rel="stylesheet">
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,[email protected],100..700,0..1"  rel="stylesheet">
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Sharp:opsz,wght,[email protected],100..700,0..1" rel="stylesheet">

<style>
md-icon {
  color: #006A6A;
  --md-icon-size: 48px;
}
.rounded {
  --md-icon-font: 'Material Symbols Rounded';
}
.sharp {
  --md-icon-font: 'Material Symbols Sharp';
}
md-icon[filled] {
  font-variation-settings: 'FILL' 1;
}
</style>

<h3>Outlined</h3>
<span>
  <md-icon>settings</md-icon>
  <md-icon>check_box</md-icon>
  <md-icon>house</md-icon>
  <md-icon filled>settings</md-icon>
  <md-icon filled>check_box</md-icon>
  <md-icon filled>house</md-icon>
</span>
<h3>Rounded</h3>
<span class="rounded">
  <md-icon>settings</md-icon>
  <md-icon>check_box</md-icon>
  <md-icon>house</md-icon>
  <md-icon filled>settings</md-icon>
  <md-icon filled>check_box</md-icon>
  <md-icon filled>house</md-icon>
</span>
<h3>Sharp</h3>
<span class="sharp">
  <md-icon>settings</md-icon>
  <md-icon>check_box</md-icon>
  <md-icon>house</md-icon>
  <md-icon filled>settings</md-icon>
  <md-icon filled>check_box</md-icon>
  <md-icon filled>house</md-icon>
</span>

Components List (`docs/components/list.md`)

Lists

This documentation is fully rendered on the
Material Web catalog

Lists are continuous,
vertical indexes of text and images

Usage

<md-list> is a container composed of <md-list-item>s of different types.

Three items in a list. The first item says Apple as its headline. The secondone says Banana in its headline as well as Banana is a yellow fruit as its subheader. The third list item says Cucumber in its headline and Cucumbers are longgreen fruits that are just as long as this multi-line description as its subheader which is on two lines.

html
<md-list style="max-width: 300px;">
  <md-list-item>
    Fruits
  </md-list-item>
  <md-divider></md-divider>
  <md-list-item>
    Apple
</md-list-item>
  <md-list-item>
    Banana
  </md-list-item>
  <md-list-item>
    <div slot="headline">Cucumber</div>
    <div slot="supporting-text">Cucumbers are long green fruits that are just as long as this multi-line description</div>
  </md-list-item>
  <md-list-item
      type="link"
      href="https://google.com/search?q=buy+kiwis&tbm=shop"
      target="_blank">
    <div slot="headline">Shop for Kiwis</div>
    <div slot="supporting-text">This will link you out in a new tab</div>
    <md-icon slot="end">open_in_new</md-icon>
  </md-list-item>
</md-list>

Icon Items

Icons can be slotted into list-items' start or end slot.

A list with three items and dividers separating each item. The first item hasthe Lit logo and the text Lit. The second item has the Polymer logo and the textPolymer. The third item has the Angular logo and the textAngular.

html
<md-list style="max-width: 300px">
  <md-list-item>
    Lit
    <svg  slot="start" style="height: 24px" viewBox="0 0 160 200">
      <path
        fill="currentColor"
        d="m160 80v80l-40-40zm-40 40v80l40-40zm0-80v80l-40-40zm-40 40v80l40-40zm-40-40v80l40-40zm40-40v80l-40-40zm-40 120v80l-40-40zm-40-40v80l40-40z"
      />
    </svg>
  </md-list-item>
  <md-divider></md-divider>
  <md-list-item>
    Polymer
    <md-icon slot="start">polymer</md-icon>
  </md-list-item>
  <md-divider></md-divider>
  <md-list-item>
    Angular
    <svg slot="start" style="height: 24px" viewBox="0 0 250 250">
      <polygon points="108,135.4 125,135.4 125,135.4 125,135.4 142,135.4 125,94.5   " />
      <path
        d="M125,30L125,30L125,30L31.9,63.2l14.2,123.1L125,230l0,0l0,0l78.9-43.7l14.2-123.1L125,30z M183.1,182.6h-21.7h0
          l-11.7-29.2H125h0h0h-24.7l-11.7,29.2h0H66.9h0L125,52.1l0,0l0,0l0,0l0,0L183.1,182.6L183.1,182.6z"
      />
    </svg>
  </md-list-item>
</md-list>

Image Items

Images should be slotted into list-items' start slot.

A list with three image items. The first item is a square picture of a cat andthe text Cat. The second is a picture of a kitten with the text Kitty Cat. Thethird item is a square image of an older kitten with the textCate.

html
<md-list style="max-width: 300px;">
  <md-list-item>
    Cat
    <img slot="start" style="width: 56px" src="https://placekitten.com/112/112">
  </md-list-item>
  <md-divider></md-divider>
  <md-list-item>
    Kitty Cat
    <img slot="start" style="width: 56px" src="https://placekitten.com/114/114">
  </md-list-item>
  <md-divider></md-divider>
  <md-list-item>
    Cate
    <img slot="start" style="width: 56px" src="https://placekitten.com/116/116">
  </md-list-item>
</md-list>

Accessibility

List can have its role and tabindex set via the role and tabindex
attributes, and list items can have their role and tabindex set via the
type and tabindex attributes respectively.

NOTE: List item has a limited set of types that can be set on it. This is to
ensure that your list remains accessible with all other properties and options
presented to it. See the ListItemType TypeScript type exported by list item
for the current accepted values.

By default these values are set to
role="list"
and tabindex="-1" for list, and
role="listitem"
and tabindex="0" for list items.

Theming

List and List Item supports
Material theming
and can be customized in terms of color, typography, and shape.

List & List Item

Token Default value
--md-list-container-color --md-sys-color-surface
--md-list-item-container-shape --md-sys-shape-corner-none
--md-list-item-label-text-color --md-sys-color-on-surface
--md-list-item-supporting-text-color --md-sys-color-on-surface-variant
--md-list-item-trailing-supporting-text-color --md-sys-color-on-surface-variant
--md-list-item-label-text-font --md-sys-typescale-label-large-font
--md-list-item-supporting-text-font --md-sys-typescale-body-medium-font
--md-list-item-trailing-supporting-text-font --md-sys-typescale-label-small-font

List & List Item Example

Image of a list and list items of foods with their inventory stock number witha different theme applied

html
<style>
  :root {
    --md-list-container-color: #f4fbfa;
    --md-list-item-label-text-color: #161d1d;
    --md-list-item-supporting-text-color: #3f4948;
    --md-list-item-trailing-supporting-text-color: #3f4948;
    --md-list-item-label-text-font: system-ui;
    --md-list-item-supporting-text-font: system-ui;
    --md-list-item-trailing-supporting-text-font: system-ui;
  }
  [slot="trailing-supporting-text"] {
    width: 30px;
    text-align: end;
  }
</style>
<md-list>
  <md-list-item type="button">
    <div slot="headline">Apple</div>
    <div slot="supporting-text">In stock</div>
    <div slot="trailing-supporting-text">+100</div>
  </md-list-item>
  <md-list-item type="button">
    <div slot="headline">Banana</div>
    <div slot="supporting-text">In stock</div>
    <div slot="trailing-supporting-text">56</div>
  </md-list-item>
  <md-list-item type="button">
    <div slot="headline">Cucumber</div>
    <div slot="supporting-text">Low stock</div>
    <div slot="trailing-supporting-text">5</div>
  </md-list-item>
</md-list>

Icon List Item

Token Default value
--md-list-item-leading-icon-color --md-sys-color-on-surface-variant
--md-list-item-trailing-icon-color --md-sys-color-on-surface-variant
--md-list-item-leading-icon-size 18px
--md-list-item-trailing-icon-size 24px

Icon List Item Example

Image of a list and icon list items of food names with a different themeapplied

html
<style>
  :root {
    background-color: #f4fbfa;
    --md-list-container-color: #f4fbfa;
    --md-list-item-label-text-color: #161d1d;
    --md-list-item-leading-icon-color: #006a6a;
    --md-list-item-trailing-icon-color: #006a6a;
    --md-list-item-leading-icon-size: 20px;
    --md-list-item-trailing-icon-size: 20px;
  }
  md-list-item.unhealthy {
    --md-list-item-trailing-icon-color: #ba1a1a;
  }
</style>
<md-list>
  <md-list-item>
    <div slot="headline">Eggs</div>
    <md-icon slot="start">egg</md-icon>
    <md-icon slot="end">recommend</md-icon>
  </md-list-item>
  <md-list-item class="unhealthy">
    <div slot="headline">Ice Cream</div>
    <md-icon slot="start">icecream</md-icon>
    <md-icon slot="end">dangerous</md-icon>
  </md-list-item>
  <md-list-item>
    <div slot="headline">Orange</div>
    <md-icon slot="start">nutrition</md-icon>
    <md-icon slot="end">recommend</md-icon>
  </md-list-item>
</md-list>

Avatar List Item

Token Default value
--md-list-item-leading-avatar-label-color --md-sys-color-on-primary-container
--md-list-item-leading-avatar-label-font --md-sys-typescale-title-medium-font
--md-list-item-leading-avatar-color --md-sys-color-primary-container
--md-list-item-leading-avatar-size 40px
--md-list-item-leading-avatar-shape --md-sys-shape-corner-full

Image List Item

Token Default value
--md-list-item-leading-image-height 56px
--md-list-item-leading-image-width 56px
--md-list-item-leading-image-shape --md-sys-shape-corner-none

Image List Item Example

html
<style>
  :root {
    background-color: #f4fbfa;
    --md-list-container-color: #f4fbfa;
    --md-list-item-label-text-color: #161d1d;
    --md-list-item-leading-image-height: 50px;
    --md-list-item-leading-image-width: 100px;
    --md-list-item-leading-image-shape: 25px;
  }
  img {
    width: 40px;
  }
</style>
<md-list>
  <md-list-item headline="Wide Cat">
    <img slot="start" src="https://placekitten.com/200/100">
  </md-list-item>
  <md-list-item headline="Round kitty cat">
    <img slot="start" src="https://placekitten.com/202/101">
  </md-list-item>
  <md-list-item headline="Softe cate">
    <img slot="start" src="https://placekitten.com/212/106">
  </md-list-item>
</md-list>

API

MdList `<md-list>`

Properties

Property Attribute Type Default Description
items ListItem[] undefined

Methods

Method Parameters Returns Description
activateNextItem None ListItem Activates the next item in the list. If at the end of the list, the first item will be activated.
activatePreviousItem None ListItem Activates the previous item in the list. If at the start of the list, the last item will be activated.

MdListItem `<md-list-item>`

Properties

Property Attribute Type Default Description
disabled disabled boolean false Disables the item and makes it non-selectable and non-interactive.
type type ListItemType 'text' Sets the behavior of the list item, defaults to "text". Change to "link" or "button" for interactive items.
href href string '' Sets the underlying HTMLAnchorElement's href resource attribute.
target target "" | "_blank" | "_parent" | "_self" | "_top" '' Sets the underlying HTMLAnchorElement's target attribute when href is set.

Methods

Method Parameters Returns Description
click None void

Events

Event Type Bubbles Composed Description
request-activation Event Yes Yes Requests the list to set tabindex=0 on the item and focus it. Used internally for list keyboard navigation; most applications do not need to listen for this event. It is exposed for authors building their own list-item replacements or wrapping items in a custom controller.

Components Menu (`docs/components/menu.md`)

This documentation is fully rendered on the
Material Web catalog.

Menus display a list of
choices on a temporary surface.

Usage

When opened, menus position themselves to an anchor. Thus, either anchor or
anchorElement must be supplied to md-menu before opening. Additionally, a
shared parent of position:relative should be present around the menu and it's
anchor, because the default menu is positioned relative to the anchor element.

Menus also render menu items such as md-menu-item and handle keyboard
navigation between md-menu-items as well as typeahead functionality.
Additionally, md-menu interacts with md-menu-items to help you determine how
a menu was closed. Listen for and inspect the close-menu custom event's
details to determine what action and items closed the menu.

"Two filled buttons next to each other. The first one says set with idref andthe other says set with element ref. There is an opened menu anchored to thebottom of the right button with the items: Apple, Banana,Cucumber."

text
/* Detailed source-code truncated for AI context efficiency. */

You can compose <md-menu>s inside of an <md-sub-menu>'s menu slot, but
first the has-overflow attribute must be set on the root <md-menu> to
disable overflow scrolling and display the nested submenus.

"A filled button that says menu with submenus. There is a menu anchored to thebottom of it with the first item selected that says fruits with A followed by aright arrow. To the right is anchored a submenu with 3 items, Apricot, Avocado,Apples. The Apples item is selected and has a left arrow before the text andanother submenu anchored to it on the left. That menu has three items, Fuji,Granny Smith, and Red Delicious."

text
/* Detailed source-code truncated for AI context efficiency. */

Popover-positioned menus

Internally menu uses position: absolute by default. Though there are cases
when the anchor and the node cannot share a common ancestor that is position: relative, or sometimes, menu will render below another item due to limitations
with position: absolute.

Popover-positioned menus use the native
Popover API
to render above all other content. This may fix most issues where the default
menu positioning (positioning="absolute") is not positioning as expected by
rendering into the
top layer.

Warning: Popover API support was added in Chrome 114 and Safari 17. At the
time of writing, Firefox does not support the Popover API
(see latest browser compatibility).

For browsers that do not support the Popover API, md-menu will fall back to
using fixed-positioned menus.

"A filled button that says open popover menu. There is an open menu anchoredto the bottom of the button with three items, Apple, Banana, andCucumber."

html
<div style="margin: 16px;">
  <md-filled-button id="usage-popover-anchor">Open popover menu</md-filled-button>
</div>


<md-menu positioning="popover" id="usage-popover" anchor="usage-popover-anchor">
  <md-menu-item>
    <div slot="headline">Apple</div>
  </md-menu-item>
  <md-menu-item>
    <div slot="headline">Banana</div>
  </md-menu-item>
  <md-menu-item>
    <div slot="headline">Cucumber</div>
  </md-menu-item>
</md-menu>

<script type="module">
  const anchorEl = document.body.querySelector('#usage-popover-anchor');
  const menuEl = document.body.querySelector('#usage-popover');

  anchorEl.addEventListener('click', () => { menuEl.open = !menuEl.open; });
</script>

Fixed-positioned menus

This is the fallback implementation of
popover-positioned menus and uses position: fixed
rather than the default position: absolute which calculates its position
relative to the window rather than the element.

Note: Fixed menu positions are positioned relative to the window and not the
document. This means that the menu will not scroll with the anchor as the page
is scrolled.

"A filled button that says open fixed menu. There is an open menu anchored tothe bottom of the button with three items, Apple, Banana, andCucumber."

html
<div style="margin: 16px;">
  <md-filled-button id="usage-fixed-anchor">Open fixed menu</md-filled-button>
</div>


<md-menu positioning="fixed" id="usage-fixed" anchor="usage-fixed-anchor">
  <md-menu-item>
    <div slot="headline">Apple</div>
  </md-menu-item>
  <md-menu-item>
    <div slot="headline">Banana</div>
  </md-menu-item>
  <md-menu-item>
    <div slot="headline">Cucumber</div>
  </md-menu-item>
</md-menu>

<script type="module">
  const anchorEl = document.body.querySelector('#usage-fixed-anchor');
  const menuEl = document.body.querySelector('#usage-fixed');

  anchorEl.addEventListener('click', () => { menuEl.open = !menuEl.open; });
</script>

Document-positioned menus

When set to positioning="document", md-menu will position itself relative to
the document as opposed to the element or the window from "absolute" and
"fixed" values respectively.

Document level positioning is useful for the following cases:

  • There are no ancestor elements that produce a relative positioning
    context.

    • position: relative
    • position: absolute
    • position: fixed
    • transform: translate(x, y)
    • etc.

  • The menu is hoisted to the top of the DOM

  • The same md-menu is being reused and the contents and anchors are being
    dynamically changed

"A filled button that says open document menu. There is an open menu anchoredto the bottom of the button with three items, Apple, Banana, andCucumber."

html
<div style="margin: 16px;">
  <md-filled-button id="usage-document-anchor">Open document menu</md-filled-button>
</div>


<md-menu positioning="document" id="usage-document" anchor="usage-document-anchor">
  <md-menu-item>
    <div slot="headline">Apple</div>
  </md-menu-item>
  <md-menu-item>
    <div slot="headline">Banana</div>
  </md-menu-item>
  <md-menu-item>
    <div slot="headline">Cucumber</div>
  </md-menu-item>
</md-menu>

<script type="module">
  const anchorEl = document.body.querySelector('#usage-document-anchor');
  const menuEl = document.body.querySelector('#usage-document');

  anchorEl.addEventListener('click', () => { menuEl.open = !menuEl.open; });
</script>

Accessibility

By default Menu is set up to function as a role="menu" with children as
role="menuitem". A common use case for this is the menu button example, where
you would need to add keyboard interactions to the button to open the menu
(see W3C example).

Menu can also be adapted for other use cases.

The role of the md-list inside the menu can be set with the type attribute.
The role of each individual md-menu-item can also be set with the type
attribute. Anything else slotted into the menu that is not a list item in most
cases should be set to role="none", and md-divider should have
role="separator" and tabindex="-1".

html
<md-filled-text-field
    id="textfield"
    type="combobox"
    aria-controls="menu"
    aria-autocomplete="list"
    aria-expanded="true"
    aria-activedescendant="1"
    value="Ala">
</md-filled-text-field>
<md-menu
    id="menu"
    anchor="textfield"
    role="listbox"
    aria-label="states"
    open>
  <md-menu-item type="option" id="0">
    <div slot="headline">Alabama</div>
  </md-menu-item>
  <md-divider role="separator" tabindex="-1"></md-divider>
  <md-menu-item type="option" id="1" selected aria-selected="true">
    <div slot="headline">Alabama</div>
  </md-menu-item>
</md-menu>

Theming

Menus support Material theming and can be customized in
terms of color. Additionally, md-menu composes md-list, and each menu item
extends md-list-item (see theming documentation), so most
the tokens for those components can also be used for Menu.

Token Default value
--md-menu-container-color --md-sys-color-surface-container
--md-menu-container-shape --md-sys-shape-corner-extra-small
--md-menu-item-container-color --md-sys-color-surface-container
--md-menu-item-selected-container-color --md-sys-color-secondary-container

Example

A filled button with the text Themed menu. Attached is a 3 item menu with theitems Apple, Banana, and Cucumber. They are both in a green hue and the menu hasa sharp 0px border radius.

html
<style>
  :root {
    background-color: #f4fbfa;
    --md-menu-container-color: #f4fbfa;
    --md-menu-container-shape: 0px;
    --md-sys-color-on-surface: #161d1d;
    --md-sys-typescale-body-large-font: system-ui;
  }
  md-menu-item {
    border-radius: 28px;
  }
  md-menu-item::part(focus-ring) {
    border-radius: 28px;
  }
  /* Styles for button and not relevant to menu */
  md-filled-button {
    --md-sys-color-primary: #006a6a;
    --md-sys-color-on-primary: #ffffff;
  }
</style>

<span style="position: relative">
  <md-filled-button id="theming-anchor">Themed menu</md-filled-button>
  <md-menu id="theming-menu" anchor="theming-anchor">
    <md-menu-item>
      <div slot="headline">Apple</div>
    </md-menu-item>
    <md-menu-item>
      <div slot="headline">Banana</div>
    </md-menu-item>
    <md-menu-item>
      <div slot="headline">Cucumber</div>
    </md-menu-item>
  </md-menu>
</span>

<script type="module">
  const anchorEl = document.body.querySelector("#theming-anchor");
  const menuEl = document.body.querySelector("#theming-menu");

  anchorEl.addEventListener("click", () => {
    menuEl.show();
  });
</script>

API

MdMenu `<md-menu>`

Properties

Property Attribute Type Default Description
anchor anchor string '' The ID of the element in the same root node in which the menu should align to. Overrides setting anchorElement = elementReference.NOTE: anchor or anchorElement must either be an HTMLElement or resolve to an HTMLElement in order for menu to open.
positioning positioning "absolute" | "fixed" | "document" | "popover" 'absolute' Whether the positioning algorithm should calculate relative to the parent of the anchor element (absolute), relative to the window (fixed), or relative to the document (document). popover will use the popover API to render the menu in the top-layer. If your browser does not support the popover API, it will fall back to fixed.Examples for position = 'fixed':- If there is no position:relative in the given parent tree and the surface is position:absolute - If the surface is position:fixed - If the surface is in the "top layer" - The anchor and the surface do not share a common position:relative ancestorWhen using positioning=fixed, in most cases, the menu should position itself above most other position:absolute or position:fixed elements when placed inside of them. e.g. using a menu inside of an md-dialog.NOTE: Fixed menus will not scroll with the page and will be fixed to the window instead.Examples for position = 'document':- There is no parent that creates a relative positioning context e.g. position: relative, position: absolute, transform: translate(x, y), etc. - You put the effort into hoisting the menu to the top of the DOM like the end of the `` to render over everything or in a top-layer. - You are reusing a single md-menu element that dynamically renders content.Examples for position = 'popover':- Your browser supports popover. - Most cases. Once popover is in browsers, this will become the default.
quick quick boolean false Skips the opening and closing animations.
hasOverflow has-overflow boolean false Displays overflow content like a submenu. Not required in most cases when using positioning="popover".NOTE: This may cause adverse effects if you set md-menu {max-height:...} and have items overflowing items in the "y" direction.
open open boolean false Opens the menu and makes it visible. Alternative to the .show() and .close() methods
xOffset x-offset number 0 Offsets the menu's inline alignment from the anchor by the given number in pixels. This value is direction aware and will follow the LTR / RTL direction.e.g. LTR: positive -> right, negative -> left RTL: positive -> left, negative -> right
yOffset y-offset number 0 Offsets the menu's block alignment from the anchor by the given number in pixels.e.g. positive -> down, negative -> up
noHorizontalFlip no-horizontal-flip boolean false Disable the flip behavior that usually happens on the horizontal axis when the surface would render outside the viewport.
noVerticalFlip no-vertical-flip boolean false Disable the flip behavior that usually happens on the vertical axis when the surface would render outside the viewport.
typeaheadDelay typeahead-delay number 200 The max time between the keystrokes of the typeahead menu behavior before it clears the typeahead buffer.
anchorCorner anchor-corner Corner Corner.END_START The corner of the anchor which to align the menu in the standard logical property style of - e.g. 'end-start'.NOTE: This value may not be respected by the menu positioning algorithm if the menu would render outisde the viewport. Use no-horizontal-flip or no-vertical-flip to force the usage of the value
menuCorner menu-corner Corner Corner.START_START The corner of the menu which to align the anchor in the standard logical property style of - e.g. 'start-start'.NOTE: This value may not be respected by the menu positioning algorithm if the menu would render outisde the viewport. Use no-horizontal-flip or no-vertical-flip to force the usage of the value
stayOpenOnOutsideClick stay-open-on-outside-click boolean false Keeps the user clicks outside the menu.NOTE: clicking outside may still cause focusout to close the menu so see stayOpenOnFocusout.
stayOpenOnFocusout stay-open-on-focusout boolean false Keeps the menu open when focus leaves the menu's composed subtree.NOTE: Focusout behavior will stop propagation of the focusout event. Set this property to true to opt-out of menu's focusout handling altogether.
skipRestoreFocus skip-restore-focus boolean false After closing, does not restore focus to the last focused element before the menu was opened.
defaultFocus default-focus FocusState FocusState.FIRST_ITEM The element that should be focused by default once opened.NOTE: When setting default focus to 'LIST_ROOT', remember to change tabindex to 0 and change md-menu's display to something other than display: contents when necessary.
noNavigationWrap no-navigation-wrap boolean false Turns off navigation wrapping. By default, navigating past the end of the menu items will wrap focus back to the beginning and vice versa. Use this for ARIA patterns that do not wrap focus, like combobox.
isSubmenu boolean false Whether or not the current menu is a submenu and should not handle specific navigation keys.
typeaheadController TypeaheadController function { ... } Handles typeahead navigation through the menu.
anchorElement HTMLElement & Partial<SurfacePositionTarget> undefined
items MenuItem[] undefined

Methods

Method Parameters Returns Description
getBoundingClientRect None DOMRect
getClientRects None DOMRectList
close None void
show None void
activateNextItem None MenuItem Activates the next item in the menu. If at the end of the menu, the first item will be activated.
activatePreviousItem None MenuItem Activates the previous item in the menu. If at the start of the menu, the last item will be activated.
reposition None void Repositions the menu if it is open.Useful for the case where document or window-positioned menus have their anchors moved while open.

Events

Event Type Bubbles Composed Description
opening Event No No Fired before the opening animation begins
opened Event No No Fired once the menu is open, after any animations
closing Event No No Fired before the closing animation begins
closed Event No No Fired once the menu is closed, after any animations

MdMenuItem `<md-menu-item>`

Properties

Property Attribute Type Default Description
disabled disabled boolean false Disables the item and makes it non-selectable and non-interactive.
type type MenuItemType 'menuitem' Sets the behavior and role of the menu item, defaults to "menuitem".
href href string '' Sets the underlying HTMLAnchorElement's href resource attribute.
target target "" | "_blank" | "_parent" | "_self" | "_top" '' Sets the underlying HTMLAnchorElement's target attribute when href is set.
keepOpen keep-open boolean false Keeps the menu open if clicked or keyboard selected.
selected selected boolean false Sets the item in the selected visual state when a submenu is opened.
typeaheadText string undefined

Events

Event Type Bubbles Composed Description
close-menu CustomEvent<{initiator: SelectOption, reason: Reason, itemPath: SelectOption[]}> Yes Yes Closes the encapsulating menu on closable interaction.

MdSubMenu `<md-sub-menu>`

Properties

Property Attribute Type Default Description
anchorCorner anchor-corner Corner Corner.START_END The anchorCorner to set on the submenu.
menuCorner menu-corner Corner Corner.START_START The menuCorner to set on the submenu.
hoverOpenDelay hover-open-delay number 400 The delay between mouseenter and submenu opening.
hoverCloseDelay hover-close-delay number 400 The delay between ponterleave and the submenu closing.
isSubMenu md-sub-menu boolean true READONLY: self-identifies as a menu item and sets its identifying attribute
item MenuItem undefined
menu Menu undefined

Methods

Method Parameters Returns Description
show None Promise<void> Shows the submenu.
close None Promise<void> Closes the submenu.

Events

Event Type Bubbles Composed Description
deactivate-items Event Yes Yes Requests the parent menu to deselect other items when a submenu opens.
request-activation Event Yes Yes Requests the parent to make the slotted item focusable and focus the item. Used internally for menu keyboard navigation; most applications do not need to listen for this event. It is exposed for authors building their own menu-item replacements, or for advanced cases where you want to call preventDefault/stopPropagation on it to override default focus handling.
deactivate-typeahead Event Yes Yes Requests the parent menu to deactivate the typeahead functionality when a submenu opens.
activate-typeahead Event Yes Yes Requests the parent menu to activate the typeahead functionality when a submenu closes.

Components Progress (`docs/components/progress.md`)

Progress indicators

This documentation is fully rendered on the
Material Web catalog.

Progress indicators
inform users about the status of ongoing processes, such as loading an app or
submitting a form.

There are two types of progress indicators: linear and circular.

Types

  1. Circular progress
  2. Linear progress

Usage

Progress indicators may be determinate to show progress, or indeterminate for an
unspecified amount of progress.

html
<md-circular-progress value="0.75"></md-circular-progress>
<md-circular-progress indeterminate></md-circular-progress>

<md-linear-progress indeterminate></md-linear-progress>
<md-linear-progress value="0.5"></md-linear-progress>

Four colors

Indeterminate progress indicators may cycle between four colors (primary,
primary container, tertiary, and tertiary container by default).

html
<md-circular-progress four-color indeterminate></md-circular-progress>
<md-linear-progress four-color indeterminate></md-linear-progress>

Accessibility

Add an
aria-label
attribute to progress indicators to give them a descriptive name.

html
<md-circular-progress value="0.5" aria-label="Page refresh progress"></md-circular-progress>

<md-linear-progress value="0.5" aria-label="Download progress"></md-linear-progress>

Circular progress

Circular progress indicators display progress by animating along an invisible
circular track in a clockwise direction.

html
<md-circular-progress indeterminate></md-circular-progress>
<md-circular-progress value="0.6"></md-circular-progress>

Linear progress

Linear progress indicators display progress by animating along the length of a
fixed, visible track.

html
<md-linear-progress indeterminate></md-linear-progress>
<md-linear-progress value="0.6"></md-linear-progress>

Buffer

Linear progress indicators may show a buffer to communicate both determinate and
indeterminate progress. The progress bar and track represent known progress
while the buffer dots represent unknown progress.

html
<md-linear-progress value="0.5" buffer="0.8"></md-linear-progress>

Theming

Progress indicators supports Material theming and can be
customized in terms of color.

Circular progress tokens

Token Default value
--md-circular-progress-active-indicator-color --md-sys-color-primary
--md-circular-progress-size 48px
--md-circular-progress-active-indicator-width 8.3333 (%)

Note: the active indicator width must be specified as a unit-less percentage
of the size.

Circular progress example

html
<style>
:root {
  --md-circular-progress-size: 32px;
  --md-circular-progress-active-indicator-width: 20;
  --md-sys-color-primary: #006A6A;
}
</style>

<md-circular-progress value="0.5"></md-circular-progress>

Linear progress tokens

Token Default value
--md-linear-progress-track-color --md-sys-color-surface-container-highest
--md-linear-progress-track-height 4px
--md-linear-progress-track-shape --md-sys-shape-corner-none
--md-linear-progress-active-indicator-color --md-sys-color-primary
--md-linear-progress-active-indicator-height 4px

Linear progress example

html
<style>
:root {
  --md-linear-progress-track-height: 8px;
  --md-linear-progress-track-shape: 8px;
  --md-linear-progress-active-indicator-height: 8px;
  --md-sys-color-primary: #006A6A;
  --md-sys-color-surface-container-highest: #DDE4E3;
}
</style>

<md-linear-progress value="0.5"></md-linear-progress>

API

MdLinearProgress `<md-linear-progress>`

Properties

Property Attribute Type Default Description
buffer buffer number 0 Buffer amount to display, a fraction between 0 and max. If the value is 0 or negative, the buffer is not displayed.
value value number 0 Progress to display, a fraction between 0 and max.
max max number 1 Maximum progress to display, defaults to 1.
indeterminate indeterminate boolean false Whether or not to display indeterminate progress, which gives no indication to how long an activity will take.
fourColor four-color boolean false Whether or not to render indeterminate mode using 4 colors instead of one.

MdCircularProgress `<md-circular-progress>`

Properties

Property Attribute Type Default Description
value value number 0 Progress to display, a fraction between 0 and max.
max max number 1 Maximum progress to display, defaults to 1.
indeterminate indeterminate boolean false Whether or not to display indeterminate progress, which gives no indication to how long an activity will take.
fourColor four-color boolean false Whether or not to render indeterminate mode using 4 colors instead of one.

Components Radio (`docs/components/radio.md`)

Radio button

Radio buttons let
people select one option from a set of options.

Usage

Radios behave like
``
elements and form a group with the same name attribute. Only one radio can be
selected in a group.

Radios can be pre-selected by adding a checked attribute.

Add a value to identify which radio is selected in a form.

html
<form>
  <md-radio name="animals" value="cats"></md-radio>
  <md-radio name="animals" value="dogs"></md-radio>
  <md-radio name="animals" value="birds" checked></md-radio>
</form>

Label

Associate a label with a radio using the <label> element.

html
<md-radio id="cats-radio" name="animals" value="cats"></md-radio>
<label for="cats-radio">Cats</label>

<md-radio id="dogs-radio" name="animals" value="dogs"></md-radio>
<label for="dogs-radio">Dogs</label>

Note: do not wrap radios inside of a <label>, which stops screen readers
from correctly announcing the number of radios in a group.

Accessibility

Add an
aria-label
attribute to radios without labels or radios whose labels need to be more
descriptive.

Place radios inside a
role="radiogroup".
Radio groups must display a label, either with aria-label or
aria-labelledby.

html
<div role="radiogroup" aria-labelledby="group-title">
  <h3 id="group-title">Starting position</h3>
  <div>
    <md-radio id="first-radio" name="group" value="1"
        aria-label="First"></md-radio>
    <label for="first-radio">1st</label>
  </div>
  <div>
    <md-radio id="second-radio" name="group" value="2"
        aria-label="Second"></md-radio>
    <label for="second-radio">2nd</label>
  </div>
</div>

Note: radios are not automatically labelled by <label> elements and always
need an aria-label. See b/294081528.

Theming

Radios support Material theming and can be customized in
terms of color.

Tokens

Token Default value
--md-radio-icon-color --md-sys-color-on-surface-variant
--md-radio-selected-icon-color --md-sys-color-primary
--md-radio-icon-size 20px

Example

html
<style>
:root {
  --md-sys-color-primary: #006A6A;
  --md-radio-icon-size: 16px;
}
</style>

<md-radio name="group"></md-radio>
<md-radio name="group" checked></md-radio>
<md-radio name="group"></md-radio>

API

MdRadio `<md-radio>`

Properties

Property Attribute Type Default Description
required required boolean false Whether or not the radio is required. If any radio is required in a group, all radios are implicitly required.
value value string 'on' The element value to use in form submission when checked.
checked checked boolean undefined
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.
validity ValidityState undefined Returns a ValidityState object that represents the validity states of the element.https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
validationMessage string undefined Returns a validation error message or an empty string if the element is valid.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
willValidate boolean undefined Returns whether an element will successfully validate based on forms validation rules and constraints.Disabled and readonly elements will not validate.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate

Methods

Method Parameters Returns Description
formResetCallback None void
formStateRestoreCallback state void
checkValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch an invalid event.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
reportValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch a cancelable invalid event. If not canceled, a the current validationMessage will be reported to the user.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
setCustomValidity error void Sets the element's constraint validation error message. When set to a non-empty string, validity.customError will be true and validationMessage will display the provided error.Use this method to customize error messages reported.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity

Events

Event Type Bubbles Composed Description
input InputEvent Yes No Dispatched when the value changes from user interaction.
change Event Yes Yes Dispatched when the value changes from user interaction.

Components Ripple (`docs/components/ripple.md`)

Ripple

This documentation is fully rendered on the
Material Web catalog

Ripples are
state layers
used to communicate the status of a component or interactive element.

A state layer is a semi-transparent covering on an element that indicates its
state. A layer can be applied to an entire element or in a circular shape.

Usage

Ripples display on hover and press pointer interactions. They may be attached to
a control in one of three ways.

  1. Attached to the parent element

    html
    <style>
  .container {
    position: relative;
  }
</style>
<button class="container">
  <md-ripple></md-ripple>
</button>

  2. Attached to a referenced element

    html
    <style>
  .container {
    position: relative;
  }
</style>
<div class="container">
  <md-ripple for="control"></md-ripple>
  <input id="control">
</div>

  3. Attached imperatively

    html
    <style>
  .container {
    position: relative;
  }
</style>
<div class="container">
  <md-ripple id="ripple"></md-ripple>
  <button id="ripple-control"></button>
</div>
<script>
  const ripple = document.querySelector('#ripple');
  const control = document.querySelector('#ripple-control');
  ripple.attach(control);
</script>

Note: ripples must be placed within a position: relative container.

Unbounded

To create an unbounded circular ripple centered on an element, use the following styles.

css
.container {
  display: flex;
  place-content: center;
  place-items: center;
  position: relative;
}

md-ripple.unbounded {
  border-radius: 50%;
  inset: unset;
  height: var(--state-layer-size);
  width: var(--state-layer-size);
}
html
<style>
  .container {
    border-radius: 50%;
    height: 32px;
    width: 32px;

    /* Needed for unbounded ripple */
    display: flex;
    place-content: center;
    place-items: center;
    position: relative;
  }

  md-ripple.unbounded {
    /* Needed for unbounded ripple */
    border-radius: 50%;
    inset: unset;
    height: 64px;
    width: 64px;
  }
</style>
<button class="container">
  <md-ripple class="unbounded"></md-ripple>
</button>

Accessibility

Ripples are visual components and do not have assistive technology requirements.

Theming

Ripples support Material theming and can be customized
in terms of color.

Tokens

Token Default value
--md-ripple-hover-color --md-sys-color-on-surface
--md-ripple-pressed-color --md-sys-color-on-surface

Example

html
<style>
:root {
  --md-sys-color-primary: #006A6A;
  --md-ripple-hover-color: var(--md-sys-color-primary);
  --md-ripple-pressed-color: var(--md-sys-color-primary);
}

.container {
  position: relative;
}
</style>
<button class="container">
  <md-ripple></md-ripple>
</button>

API

MdRipple `<md-ripple>`

Properties

Property Attribute Type Default Description
disabled disabled boolean false Disables the ripple.
htmlFor string undefined
control HTMLElement undefined

Methods

Method Parameters Returns Description
attach control void
detach None void

Components Select (`docs/components/select.md`)

Select

This documentation is fully rendered on the
Material Web catalog

Select menus
display a list of choices on temporary surfaces and display the currently
selected menu item above the menu.

Usage

Select (also referred to as a dropdown menu) allows choosing a value from a
fixed list of available options. It is analogous to the native HTML
<select> element.

html
<md-outlined-select>
  <md-select-option aria-label="blank"></md-select-option>
  <md-select-option selected value="apple">
    <div slot="headline">Apple</div>
  </md-select-option>
  <md-select-option value="apricot">
    <div slot="headline">Apricot</div>
  </md-select-option>
</md-outlined-select>

<md-filled-select>
  <md-select-option aria-label="blank"></md-select-option>
  <md-select-option value="apple">
    <div slot="headline">Apple</div>
  </md-select-option>
  <md-select-option value="apricot">
    <div slot="headline">Apricot</div>
  </md-select-option>
</md-filled-select>

Required select

Indicate that a selection is mandatory by adding the required attribute.

html
<md-filled-select required>
  <md-select-option value="one">
    <div slot="headline">One</div>
  </md-select-option>
  <md-select-option value="two">
    <div slot="headline">Two</div>
  </md-select-option>
</md-filled-select>

Theming

Select supports
Material theming
and can be customized in terms of color, typography, and shape.

Filled Select tokens

Token Default value
--md-filled-select-text-field-container-color --md-sys-color-surface-container-highest
--md-filled-select-text-field-container-shape --md-sys-shape-corner-extra-small
--md-filled-select-text-field-input-text-color --md-sys-color-on-surface
--md-filled-select-text-field-input-text-font --md-sys-typescale-body-large-font

To theme the select's dropdown menu, use the md-menu component tokens on the
::part(menu) selector.

Filled Select example

html
<style>
:root {
  --md-filled-select-text-field-container-shape: 0px;
  --md-filled-select-text-field-container-color: #f7faf9;
  --md-filled-select-text-field-input-text-color: #005353;
  --md-filled-select-text-field-input-text-font: system-ui;
}

md-filled-select::part(menu) {
  --md-menu-container-color: #f4fbfa;
  --md-menu-container-shape: 0px;
}
</style>

<md-filled-select>
  <md-select-option selected value="apple">
    <div slot="headline">Apple</div>
  </md-select-option>
  <md-select-option value="tomato">
    <div slot="headline">Tomato</div>
  </md-select-option>
</md-filled-select>

Outlined Select tokens

Token Default value
--md-outlined-select-text-field-outline-color --md-sys-color-outline
--md-outlined-select-text-field-container-shape --md-sys-shape-corner-extra-small
--md-outlined-select-text-field-input-text-color --md-sys-color-on-surface
--md-outlined-select-text-field-input-text-font --md-sys-typescale-body-large-font

Outlined Select example

html
<style>
:root {
  --md-outlined-select-text-field-outline-color: #6e7979;
  --md-outlined-select-text-field-container-shape: 0px;
  --md-outlined-select-text-field-input-text-color: #005353;
  --md-outlined-select-text-field-input-text-font: system-ui;
}

md-outlined-select::part(menu) {
  --md-menu-container-color: #f4fbfa;
  --md-menu-container-shape: 0px;
}
</style>

<md-outlined-select>
  <md-select-option selected value="apple">
    <div slot="headline">Apple</div>
  </md-select-option>
  <md-select-option value="tomato">
    <div slot="headline">Tomato</div>
  </md-select-option>
</md-outlined-select>

API

MdFilledSelect `<md-filled-select>`

Properties

Property Attribute Type Default Description
quick quick boolean false Opens the menu synchronously with no animation.
required required boolean false Whether or not the select is required.
errorText error-text string '' The error message that replaces supporting text when error is true. If errorText is an empty string, then the supporting text will continue to show.This error message overrides the error message displayed by reportValidity().
label label string '' The floating label for the field.
noAsterisk no-asterisk boolean false Disables the asterisk on the floating label, when the select is required.
supportingText supporting-text string '' Conveys additional information below the select, such as how it should be used.
error error boolean false Gets or sets whether or not the select is in a visually invalid state.This error state overrides the error state controlled by reportValidity().
menuPositioning menu-positioning "absolute" | "fixed" | "popover" 'popover' Whether or not the underlying md-menu should be position: fixed to display in a top-level manner, or position: absolute.position:fixed is useful for cases where select is inside of another element with stacking context and hidden overflows such as md-dialog.
clampMenuWidth clamp-menu-width boolean false Clamps the menu-width to the width of the select.
typeaheadDelay typeahead-delay number DEFAULT_TYPEAHEAD_BUFFER_TIME The max time between the keystrokes of the typeahead select / menu behavior before it clears the typeahead buffer.
hasLeadingIcon has-leading-icon boolean false Whether or not the text field has a leading icon. Used for SSR.
displayText display-text string '' Text to display in the field. Only set for SSR.
menuAlign menu-align "start" | "end" 'start' Whether the menu should be aligned to the start or the end of the select's textbox.
value value string undefined
selectedIndex selected-index number undefined
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
options SelectOption[] undefined
selectedOptions SelectOption[] undefined
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.
validity ValidityState undefined Returns a ValidityState object that represents the validity states of the element.https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
validationMessage string undefined Returns a validation error message or an empty string if the element is valid.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
willValidate boolean undefined Returns whether an element will successfully validate based on forms validation rules and constraints.Disabled and readonly elements will not validate.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate

Methods

Method Parameters Returns Description
select value void Selects an option given the value of the option, and updates MdSelect's value.
selectIndex index void Selects an option given the index of the option, and updates MdSelect's value.
reset None void Reset the select to its default value.
showPicker None void Shows the picker. If it's already open, this is a no-op.
getUpdateComplete None Promise
formResetCallback None void
formStateRestoreCallback state void
click None void
checkValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch an invalid event.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
reportValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch a cancelable invalid event. If not canceled, a the current validationMessage will be reported to the user.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
setCustomValidity error void Sets the element's constraint validation error message. When set to a non-empty string, validity.customError will be true and validationMessage will display the provided error.Use this method to customize error messages reported.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity

Events

Event Type Bubbles Composed Description
change Event Yes No The native change event on ``
input InputEvent Yes Yes The native input event on ``
opening Event No No Fired when the select's menu is about to open.
opened Event No No Fired when the select's menu has finished animations and opened.
closing Event No No Fired when the select's menu is about to close.
closed Event No No Fired when the select's menu has finished animations and closed.

MdOutlinedSelect `<md-outlined-select>`

Properties

Property Attribute Type Default Description
quick quick boolean false Opens the menu synchronously with no animation.
required required boolean false Whether or not the select is required.
errorText error-text string '' The error message that replaces supporting text when error is true. If errorText is an empty string, then the supporting text will continue to show.This error message overrides the error message displayed by reportValidity().
label label string '' The floating label for the field.
noAsterisk no-asterisk boolean false Disables the asterisk on the floating label, when the select is required.
supportingText supporting-text string '' Conveys additional information below the select, such as how it should be used.
error error boolean false Gets or sets whether or not the select is in a visually invalid state.This error state overrides the error state controlled by reportValidity().
menuPositioning menu-positioning "absolute" | "fixed" | "popover" 'popover' Whether or not the underlying md-menu should be position: fixed to display in a top-level manner, or position: absolute.position:fixed is useful for cases where select is inside of another element with stacking context and hidden overflows such as md-dialog.
clampMenuWidth clamp-menu-width boolean false Clamps the menu-width to the width of the select.
typeaheadDelay typeahead-delay number DEFAULT_TYPEAHEAD_BUFFER_TIME The max time between the keystrokes of the typeahead select / menu behavior before it clears the typeahead buffer.
hasLeadingIcon has-leading-icon boolean false Whether or not the text field has a leading icon. Used for SSR.
displayText display-text string '' Text to display in the field. Only set for SSR.
menuAlign menu-align "start" | "end" 'start' Whether the menu should be aligned to the start or the end of the select's textbox.
value value string undefined
selectedIndex selected-index number undefined
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
options SelectOption[] undefined
selectedOptions SelectOption[] undefined
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.
validity ValidityState undefined Returns a ValidityState object that represents the validity states of the element.https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
validationMessage string undefined Returns a validation error message or an empty string if the element is valid.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
willValidate boolean undefined Returns whether an element will successfully validate based on forms validation rules and constraints.Disabled and readonly elements will not validate.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate

Methods

Method Parameters Returns Description
select value void Selects an option given the value of the option, and updates MdSelect's value.
selectIndex index void Selects an option given the index of the option, and updates MdSelect's value.
reset None void Reset the select to its default value.
showPicker None void Shows the picker. If it's already open, this is a no-op.
getUpdateComplete None Promise
formResetCallback None void
formStateRestoreCallback state void
click None void
checkValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch an invalid event.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
reportValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch a cancelable invalid event. If not canceled, a the current validationMessage will be reported to the user.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
setCustomValidity error void Sets the element's constraint validation error message. When set to a non-empty string, validity.customError will be true and validationMessage will display the provided error.Use this method to customize error messages reported.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity

Events

Event Type Bubbles Composed Description
change Event Yes No The native change event on ``
input InputEvent Yes Yes The native input event on ``
opening Event No No Fired when the select's menu is about to open.
opened Event No No Fired when the select's menu has finished animations and opened.
closing Event No No Fired when the select's menu is about to close.
closed Event No No Fired when the select's menu has finished animations and closed.

MdSelectOption `<md-select-option>`

Properties

Property Attribute Type Default Description
disabled disabled boolean false Disables the item and makes it non-selectable and non-interactive.
selected selected boolean false Sets the item in the selected visual state when a submenu is opened.
value value string '' Form value of the option.
type string 'option' as const
typeaheadText string undefined
displayText string undefined

Events

Event Type Bubbles Composed Description
close-menu CustomEvent<{initiator: SelectOption, reason: Reason, itemPath: SelectOption[]}> Yes Yes Closes the encapsulating menu on closable interaction.
request-selection Event Yes Yes Requests the parent md-select to select this element (and deselect others if single-selection) when selected changed to true.
request-deselection Event Yes Yes Requests the parent md-select to deselect this element when selected changed to false.

Components Slider (`docs/components/slider.md`)

Sliders

This documentation is fully rendered on the
Material Web catalog

Sliders allow users to
view and select a value (or range) along a track. They're ideal for adjusting
settings such as volume and brightness, or for applying image filters.

Sliders can use icons or labels to represent a numeric or relative scale.

Usage

Sliders may be continuous or discrete, and may also represent a range.

html
<md-slider></md-slider>
<md-slider ticks value="50"></md-slider>
<md-slider range value-start="25" value-end="75"></md-slider>

Continuous

Allows users to select a value along a subjective range.

html
<md-slider min="0" max="100" value="50"></md-slider>

Discrete

Allows users to select a specific value from a predetermined range. Tick marks
may be used to indicate available values.

html
<md-slider step="5" ticks min="0" max="20"></md-slider>

Range

A range slider has two handles, and indicates a minimum and maximum value in a
range.

html
<md-slider range value-start="25" value-end="50"></md-slider>

Value label

A value label displays the specific value that corresponds with the handle's
placement.

The label appears when the handle is selected. For range sliders, labels appear
when either handle is selected.

html
<md-slider labeled></md-slider>

Theming

Slider supports Material theming and can be customized
in terms of color and shape.

Tokens

Token Default value
--md-slider-active-track-color --md-sys-color-primary
--md-slider-active-track-shape --md-sys-shape-corner-full
--md-slider-inactive-track-color --md-sys-color-surface-container-highest
--md-slider-inactive-track-shape --md-sys-shape-corner-full
--md-slider-handle-color --md-sys-color-primary
--md-slider-handle-shape --md-sys-shape-corner-full

Example

html
<style>
:root {
  /* System tokens */
  --md-sys-color-primary: #006A6A;

  /* Component tokens */
  --md-slider-handle-shape: 0px;
}
</style>

<md-slider
  range
  value-start="25"
  value-end="75"
  ticks
  step="5"
></md-slider>

API

MdSlider `<md-slider>`

Properties

Property Attribute Type Default Description
min min number 0 The slider minimum value
max max number 100 The slider maximum value
value value number undefined The slider value displayed when range is false.
valueStart value-start number undefined The slider start value displayed when range is true.
valueEnd value-end number undefined The slider end value displayed when range is true.
valueLabel value-label string '' An optional label for the slider's value displayed when range is false; if not set, the label is the value itself.
valueLabelStart value-label-start string '' An optional label for the slider's start value displayed when range is true; if not set, the label is the valueStart itself.
valueLabelEnd value-label-end string '' An optional label for the slider's end value displayed when range is true; if not set, the label is the valueEnd itself.
ariaLabelStart aria-label-start string '' Aria label for the slider's start handle displayed when range is true.
ariaValueTextStart aria-valuetext-start string '' Aria value text for the slider's start value displayed when range is true.
ariaLabelEnd aria-label-end string '' Aria label for the slider's end handle displayed when range is true.
ariaValueTextEnd aria-valuetext-end string '' Aria value text for the slider's end value displayed when range is true.
step step number 1 The step between values.
ticks ticks boolean false Whether or not to show tick marks.
labeled labeled boolean false Whether or not to show a value label when activated.
range range boolean false Whether or not to show a value range. When false, the slider displays a slideable handle for the value property; when true, it displays slideable handles for the valueStart and valueEnd properties.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
nameStart string undefined
nameEnd string undefined
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.

Methods

Method Parameters Returns Description
formResetCallback None void
formStateRestoreCallback state void

Events

Event Type Bubbles Composed Description
change Event Yes No The native change event on ``
input InputEvent Yes Yes The native input event on ``

Components Switch (`docs/components/switch.md`)

Switch

This documentation is fully rendered on the
Material Web catalog.

Switches toggle the state
of an item on or off.

Usage

Switches are similar to checkboxes, and can be unselected or selected.

html
<md-switch></md-switch>
<md-switch selected></md-switch>

Icons

Icons can be used to visually emphasize the switch's selected state. Switches
can choose to display both icons or only selected icons.

html
<md-switch icons></md-switch>
<md-switch icons selected></md-switch>

<md-switch icons show-only-selected-icon></md-switch>
<md-switch icons show-only-selected-icon selected></md-switch>

Label

Associate a label with a switch using the <label> element.

html
<label>
  Wi-Fi
  <md-switch selected></md-switch>
</label>

<label for="switch">Bluetooth</label>
<md-switch id="switch"></md-switch>

Accessibility

Add an
aria-label
attribute to switches without labels or switches whose labels need to be more
descriptive.

html
<md-switch aria-label="Lights"></md-switch>

<label>
  All
  <md-switch aria-label="All notifications"></md-switch>
</label>

Note: switches are not automatically labelled by <label> elements and always
need an aria-label. See b/294081528.

Theming

Switches supports Material theming and can be customized
in terms of color and shape.

Tokens

Token Default value
--md-switch-handle-color --md-sys-color-outline
--md-switch-handle-shape --md-sys-shape-corner-full
--md-switch-track-color --md-sys-color-surface-container-highest
--md-switch-track-shape --md-sys-shape-corner-full
--md-switch-selected-handle-color --md-sys-color-on-primary
--md-switch-selected-track-color --md-sys-color-primary

Example

html
<style>
  :root {
    /* System tokens */
    --md-sys-color-primary: #006a6a;
    --md-sys-color-on-primary: #ffffff;
    --md-sys-color-outline: #6f7979;
    --md-sys-color-surface-container-highest: #dde4e3;

    /* Component tokens */
    --md-switch-handle-shape: 0px;
    --md-switch-track-shape: 0px;
  }
</style>

<md-switch></md-switch>
<md-switch selected></md-switch>

API

MdSwitch `<md-switch>`

Properties

Property Attribute Type Default Description
selected selected boolean false Puts the switch in the selected state and sets the form submission value to the value property.
icons icons boolean false Shows both the selected and deselected icons.
showOnlySelectedIcon show-only-selected-icon boolean false Shows only the selected icon, and not the deselected icon. If true, overrides the behavior of the icons property.
required required boolean false When true, require the switch to be selected when participating in form submission.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#validation
value value string 'on' The value associated with this switch on form submission. null is submitted when selected is false.
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.
validity ValidityState undefined Returns a ValidityState object that represents the validity states of the element.https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
validationMessage string undefined Returns a validation error message or an empty string if the element is valid.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
willValidate boolean undefined Returns whether an element will successfully validate based on forms validation rules and constraints.Disabled and readonly elements will not validate.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate

Methods

Method Parameters Returns Description
formResetCallback None void
formStateRestoreCallback state void
checkValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch an invalid event.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
reportValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch a cancelable invalid event. If not canceled, a the current validationMessage will be reported to the user.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
setCustomValidity error void Sets the element's constraint validation error message. When set to a non-empty string, validity.customError will be true and validationMessage will display the provided error.Use this method to customize error messages reported.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity

Events

Event Type Bubbles Composed Description
input InputEvent No No Fired whenever selected changes due to user interaction (bubbles and composed).
change Event No No Fired whenever selected changes due to user interaction (bubbles).

Components Tabs (`docs/components/tabs.md`)

Tabs

This documentation is fully rendered on the
Material Web catalog

Tabs organize groups of
related content that are at the same level of hierarchy.

Types

  1. Primary tabs
  2. Secondary tabs

Usage

Tabs contain multiple primary or secondary tab children. Use the same type of
tab in a tab bar.

html
<md-tabs>
  <md-primary-tab>Video</md-primary-tab>
  <md-primary-tab>Photos</md-primary-tab>
  <md-primary-tab>Audio</md-primary-tab>
</md-tabs>

<md-tabs>
  <md-secondary-tab>Birds</md-secondary-tab>
  <md-secondary-tab>Cats</md-secondary-tab>
  <md-secondary-tab>Dogs</md-secondary-tab>
</md-tabs>

Selection

Add an active attribute to change which tab is selected.

html
<md-tabs>
  <md-primary-tab>Video</md-primary-tab>
  <md-primary-tab active>Photos</md-primary-tab>
  <md-primary-tab>Audio</md-primary-tab>
</md-tabs>

To observe changes to tab selections, add an event listener to <md-tabs>,
listening for the change event.

ts
tabs.addEventListener('change', (event: Event) => {
  if (event.target.activeTabIndex === 2) {
    // ... perform logic only if index of selected item is 2.
  }
});

Icons

Tabs may optionally show an icon.

Icons communicate the type of content within a tab. Icons should be simple and
recognizable.

html
<md-tabs>
  <md-primary-tab>
    <md-icon slot="icon">piano</md-icon>
    Keyboard
  </md-primary-tab>
  <md-primary-tab>
    <md-icon slot="icon">tune</md-icon>
    Guitar
  </md-primary-tab>
</md-tabs>

Tabs may optionally show icons without a label.

html
<md-tabs>
  <md-primary-tab>
    <md-icon slot="icon">piano</md-icon>
  </md-primary-tab>
  <md-primary-tab>
    <md-icon slot="icon">tune</md-icon>
  </md-primary-tab>
</md-tabs>

Primary tabs

Primary tabs are placed at the top of the content pane under a top app bar. They
display the main content destinations.

html
<md-tabs>
  <md-primary-tab>
    <md-icon slot="icon">piano</md-icon>
    Keyboard
  </md-primary-tab>
  <md-primary-tab>
    <md-icon slot="icon">tune</md-icon>
    Guitar
  </md-primary-tab>
</md-tabs>

Inline icons

Primary tabs can show their icons inline, like secondary tabs.

html
<md-tabs>
  <md-primary-tab inline-icon>
    <md-icon slot="icon">piano</md-icon>
    Keyboard
  </md-primary-tab>
  <md-primary-tab inline-icon>
    <md-icon slot="icon">tune</md-icon>
    Guitar
  </md-primary-tab>
</md-tabs>

Secondary tabs

Secondary tabs are used within a content area to further separate related
content and establish hierarchy.

html
<md-tabs>
  <md-secondary-tab>
    <md-icon slot="icon">flight</md-icon>
    Travel
  </md-secondary-tab>
  <md-secondary-tab>
    <md-icon slot="icon">hotel</md-icon>
    Hotel
  </md-secondary-tab>
  <md-secondary-tab>
    <md-icon slot="icon">hiking</md-icon>
    Activities
  </md-secondary-tab>
</md-tabs>

Accessibility

Add an
aria-label
attribute to <md-tabs> and any individual tab whose label needs to be more
descriptive, such as icon-only tabs.

html
<md-tabs aria-label="Content to view">
  <md-primary-tab aria-label="Photos">
    <md-icon slot="icon">photo</md-icon>
  </md-primary-tab>
  <md-primary-tab aria-label="Videos">
    <md-icon slot="icon">videocam</md-icon>
  </md-primary-tab>
  <md-primary-tab aria-label="Music">
    <md-icon slot="icon">audiotrack</md-icon>
  </md-primary-tab>
</md-tabs>

Tab panels

Every tab must reference a
role="tabpanel"
element with aria-controls. Tab panels must be labelled with aria-label or
aria-labelledby.

It's common to reference the panel's tab with aria-labelledby.

html
<md-tabs aria-label="Content to view">
  <md-primary-tab id="photos-tab" aria-controls="photos-panel">
    Photos
  </md-primary-tab>
  <md-primary-tab id="videos-tab" aria-controls="videos-panel">
    Videos
  </md-primary-tab>
  <md-primary-tab id="music-tab" aria-controls="music-panel">
    Music
  </md-primary-tab>
</md-tabs>

<div id="photos-panel" role="tabpanel" aria-labelledby="photos-tab">
  ...
</div>
<div id="videos-panel" role="tabpanel" aria-labelledby="videos-tab" hidden>
  ...
</div>
<div id="music-panel" role="tabpanel" aria-labelledby="music-tab" hidden>
  ...
</div>

Theming

Tabs supports Material theming and can be customized in
terms of color, typography, and shape.

Primary tab tokens

Token Default value
--md-primary-tab-container-color --md-sys-color-surface
--md-primary-tab-label-text-font --md-sys-typescale-title-small-font
--md-primary-tab-active-indicator-color --md-sys-color-primary
--md-primary-tab-icon-color --md-sys-color-on-surface-variant
--md-primary-tab-container-shape --md-sys-shape-corner-none

Primary tab example

html
<style>
:root {
  /* System tokens */
  --md-sys-color-surface: #f7faf9;
  --md-sys-color-primary: #005353;

  /* Component tokens */
  --md-primary-tab-label-text-font: cursive, system-ui;
  --md-primary-tab-label-text-size: 0.8em;
}
</style>

<md-tabs>
  <md-primary-tab>Tab 1</md-primary-tab>
  <md-primary-tab>Tab 2</md-primary-tab>
  <md-primary-tab>Tab 3</md-primary-tab>
</md-tabs>

Secondary tab tokens

Token Default value
--md-secondary-tab-container-color --md-sys-color-surface
--md-secondary-tab-label-text-font --md-sys-typescale-title-small-font
--md-secondary-tab-active-indicator-color --md-sys-color-primary
--md-secondary-tab-icon-color --md-sys-color-on-surface-variant
--md-secondary-tab-container-shape --md-sys-shape-corner-none

Secondary tab example

html
<style>
:root {
  /* System tokens */
  --md-sys-color-surface: #f7faf9;
  --md-sys-color-primary: #005353;

  /* Component tokens */
  --md-secondary-tab-label-text-font: cursive, system-ui;
  --md-secondary-tab-label-text-size: 0.8em;
}
</style>

<md-tabs>
  <md-secondary-tab>Tab 1</md-secondary-tab>
  <md-secondary-tab>Tab 2</md-secondary-tab>
  <md-secondary-tab>Tab 3</md-secondary-tab>
</md-tabs>

API

MdTabs `<md-tabs>`

Properties

Property Attribute Type Default Description
autoActivate auto-activate boolean false Whether or not to automatically select a tab when it is focused.
activeTabIndex active-tab-index number undefined
tabs Tab[] undefined The tabs of this tab bar.
activeTab Tab undefined

Methods

Method Parameters Returns Description
scrollToTab tabToScrollTo Promise<void> Scrolls the toolbar, if overflowing, to the active tab, or the provided tab.

Events

Event Type Bubbles Composed Description
change Event Yes No Fired when the selected tab changes. The target's activeTabIndex or activeTab provide information about the selection change. The change event is fired when a user interaction like a space/enter key or click cause a selection change. The tab selection based on these actions can be cancelled by calling preventDefault on the triggering keydown or click event.

MdPrimaryTab `<md-primary-tab>`

Properties

Property Attribute Type Default Description
inlineIcon inline-icon boolean false Whether or not the icon renders inline with label or stacked vertically.
isTab md-tab boolean true The attribute md-tab indicates that the element is a tab for the parent element, <md-tabs>. Make sure if you're implementing your own md-tab component that you have an md-tab attribute set.
active active boolean false Whether or not the tab is selected.
hasIcon has-icon boolean false In SSR, set this to true when an icon is present.
iconOnly icon-only boolean false In SSR, set this to true when there is no label and only an icon.
selected selected boolean undefined

MdSecondaryTab `<md-secondary-tab>`

Properties

Property Attribute Type Default Description
isTab md-tab boolean true The attribute md-tab indicates that the element is a tab for the parent element, <md-tabs>. Make sure if you're implementing your own md-tab component that you have an md-tab attribute set.
active active boolean false Whether or not the tab is selected.
hasIcon has-icon boolean false In SSR, set this to true when an icon is present.
iconOnly icon-only boolean false In SSR, set this to true when there is no label and only an icon.
selected selected boolean undefined

Components Text Field (`docs/components/text-field.md`)

Text field

This documentation is fully rendered on the
Material Web catalog

Text fields let
users enter text into a UI.

Types

  1. Filled text field
  2. Outlined text field

Usage

Text fields behave like
``
elements. They provide a container with labels for user input.

A filled textfield next to an outlined textfield. Both have a value of Valueprefilled

html
<md-filled-text-field label="Label" value="Value">
</md-filled-text-field>

<md-outlined-text-field label="Label" value="Value">
</md-outlined-text-field>

Input type

A text field's type attribute changes how the text field works, such as
displaying a different keyboard or providing default validation.

Two filled textfields next to each other. The first has a label of Usernameand the outlined one has a label of Password

html
<md-filled-text-field label="Username" type="email">
</md-filled-text-field>

<md-filled-text-field label="Password" type="password">
</md-filled-text-field>

Tip: use the
inputmode
attribute for more control over the displayed keyboard.

Labels

Text fields should label their value with a floating label, a placeholder,
or an external label. Labels help the user understand what value to input.

Three outlined textfields next to each other. the first has a label ofFavorite food, the second one a placeholder of email@domain.com and there is alabel that says First name and an empty outlined textfield next toit

html
<md-outlined-text-field label="Favorite food">
</md-outlined-text-field>

<md-outlined-text-field placeholder="[email protected]">
</md-outlined-text-field>

<div>First name</div>
<md-outlined-text-field aria-label="First name">
</md-outlined-text-field>

Note: text fields do not currently support aria-labelledby. External labels
must provide an aria-label. See b/276484803.

Textarea

Multi-line text fields behave like
<textarea>
elements.

Textareas can specify the initial number of rows. Use CSS width, height,
and resize to control the resize behavior of a textarea.

A filled textarea that is vertically larger and has a label that says Verticalresize

html
<style>
  md-filled-text-field {
    resize: vertical;
  }
</style>
<md-filled-text-field
    type="textarea"
    label="Vertical resize"
    rows="3">
</md-filled-text-field>

Icons

Text fields may display optional icons. Use icons to describe the input method
(such as a search icon), provide additional functionality (such as a clear
icon), or to express errors.

Three outlined textfields next to each other the first has a search icon atthe start the label Search Messages, the second a label that says Password andan eye icon toggle button at the end, and a red, visually errored outlinedtextfield with the label Username with an exclamation icon at the end and helpererror text under the field that says Username notavailable

html
<md-outlined-text-field placeholder="Search for messages">
  <md-icon slot="leading-icon">search</md-icon>
</md-outlined-text-field>

<md-outlined-text-field label="Password" type="password">
  <md-icon-button toggle slot="trailing-icon">
    <md-icon>visibility</md-icon>
    <md-icon slot="selected">visibility_off</md-icon>
  </md-icon-button>
</md-outlined-text-field>

<md-outlined-text-field
    label="Username"
    error
    error-text="Username not available">
  <md-icon slot="trailing-icon">error</md-icon>
</md-outlined-text-field>

Prefix and suffix

Add prefix-text and suffix-text attributes to text fields to display
additional context for the value.

An outlined textfield with a floating label that says Dollar amount, a prefixdollar sign, the number zero as a value and a suffix of decimal zero zero at theend of the field

html
<md-outlined-text-field
    label="Dollar amount"
    type="number"
    value="0"
    prefix-text="$"
    suffix-text=".00">
</md-outlined-text-field>

Supporting text

Supporting text conveys additional information about the input field, such as
how it will be used. Supporting text can be replaced with error text when
validating.

Two filled fields next to each other. The first has a label that says commentsand supporting text under the field that says Provide comments for the issue.The second field has a label of Name with an asterisk and supporting text underthe field that has an asterisk followed by the wordrequired

html
<md-filled-text-field
    label="Comments"
    supporting-text="Provide comments for the issue">
</md-filled-text-field>

<md-filled-text-field
    label="Name"
    required
    supporting-text="*required"
    error-text="Please fill out this field">
</md-filled-text-field>

Character counter

Text fields with a maxlength attribute will display a character counter.

An outlined textfield with a floating label that says Title and a filled valuethat says Short and the text 5 / 10 under the field at theend

html
<md-outlined-text-field label="Title" value="Short" maxlength="10">
</md-outlined-text-field>

Validation

Text fields that validate can use
constraint validation or
manual validation.

Constraint validation

Text fields may validate using the browser's
constraint validation
API. Each input type above links to an article that describes how
to validate it.

Text fields in a <form> will validate on submission, or by calling
textField.reportValidity().

html
<form>
  <md-filled-text-field
      name="name"
      label="Name"
      required>
  </md-filled-text-field>
  <md-filled-text-field
      name="email"
      label="Email"
      pattern="[\w\d-]+"
      suffix-text="@gmail.com">
  </md-filled-text-field>
</form>

Use the following properties and methods to check and report validation errors.

Manual validation

Alternatively, text fields can manually control their error state and error
message. Use manual validation if the text fields are driven by application
state logic.

html
<md-outlined-text-field
    label="Username"
    value="jdoe"
    error
    error-text="Username is not available">
</md-outlined-text-field>

Tip: Prefer constraint validation when possible for
more platform features, such as <form> validation and listening to invalid
events.

Accessibility

Add an
aria-label
attribute to text fields with external labels or text fields whose labels need
to be more descriptive.

html
<div>Username</div>
<md-filled-text-field aria-label="Username"></md-filled-text-field>

<md-filled-text-field label="First" aria-label="First name"></md-filled-text-field>

Filled text field

Filled and outlined text fields are functionally identical. See
choosing a text field
for guidance on which one to use.

html
<md-filled-text-field label="Filled" value="Value"></md-filled-text-field>

Outlined text field

Filled and outlined text fields are functionally identical. See
choosing a text field
for guidance on which one to use.

html
<md-outlined-text-field label="Outlined" value="Value"></md-outlined-text-field>

Theming

Text fields support Material theming and can be
customized in terms of color, typography, and shape.

Filled text field tokens

Token Default value
--md-filled-text-field-container-shape --md-sys-shape-corner-extra-small
--md-filled-text-field-container-color --md-sys-color-surface-container-highest
--md-filled-text-field-focus-active-indicator-color --md-sys-color-primary
--md-filled-text-field-input-text-font --md-sys-typescale-body-large-font
--md-filled-text-field-label-text-font --md-sys-typescale-body-large-font

Filled text field example

html
<style>
:root {
  --md-filled-text-field-container-shape: 0px;
  --md-sys-typescale-body-large: 400 1rem system-ui;
  --md-sys-color-primary: #006a6a;
  --md-sys-color-surface-container-highest: #e0e3e2;
  --md-filled-text-field-label-text-color: #3f4948;
  --md-filled-text-field-input-text-color: #161d1d;
}
</style>

<md-filled-text-field label="Filled" value="Value">
</md-filled-text-field>

Outlined text field tokens

Token Default value
--md-outlined-text-field-container-shape --md-sys-shape-corner-extra-small
--md-outlined-text-field-focus-outline-color --md-sys-color-primary
--md-outlined-text-field-input-text-font --md-sys-typescale-body-large-font
--md-outlined-text-field-label-text-font --md-sys-typescale-body-large-font

Outlined text field example

html
<style>
:root {
  --md-outlined-text-field-container-shape: 0px;
  --md-sys-typescale-body-large: 400 1rem system-ui;
  --md-sys-color-primary: #006a6a;
  --md-outlined-text-field-label-text-color: #3f4948;
  --md-outlined-text-field-input-text-color: #161d1d;
}
</style>

<md-outlined-text-field label="Outlined" value="Value"></md-outlined-text-field>

API

MdFilledTextField `<md-filled-text-field>`

Properties

Property Attribute Type Default Description
error error boolean false Gets or sets whether or not the text field is in a visually invalid state.This error state overrides the error state controlled by reportValidity().
errorText error-text string '' The error message that replaces supporting text when error is true. If errorText is an empty string, then the supporting text will continue to show.This error message overrides the error message displayed by reportValidity().
label label string '' The floating Material label of the textfield component. It informs the user about what information is requested for a text field. It is aligned with the input text, is always visible, and it floats when focused or when text is entered into the textfield. This label also sets accessibilty labels, but the accessible label is overriden by aria-label.Learn more about floating labels from the Material Design guidelines: https://m3.material.io/components/text-fields/guidelines
noAsterisk no-asterisk boolean false Disables the asterisk on the floating label, when the text field is required.
required required boolean false Indicates that the user must specify a value for the input before the owning form can be submitted and will render an error state when reportValidity() is invoked when value is empty. Additionally the floating label will render an asterisk "*" when true.https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/required
value value string '' The current value of the text field. It is always a string.
prefixText prefix-text string '' An optional prefix to display before the input value.
suffixText suffix-text string '' An optional suffix to display after the input value.
hasLeadingIcon has-leading-icon boolean false Whether or not the text field has a leading icon. Used for SSR.
hasTrailingIcon has-trailing-icon boolean false Whether or not the text field has a trailing icon. Used for SSR.
supportingText supporting-text string '' Conveys additional information below the text field, such as how it should be used.
textDirection text-direction string '' Override the input text CSS direction. Useful for RTL languages that use LTR notation for fractions.
rows rows number 2 The number of rows to display for a type="textarea" text field. Defaults to 2.
cols cols number 20 The number of cols to display for a type="textarea" text field. Defaults to 20.
inputMode inputmode string ''
max max string '' Defines the greatest value in the range of permitted values.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#max
maxLength maxlength number -1 The maximum number of characters a user can enter into the text field. Set to -1 for none.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#maxlength
min min string '' Defines the most negative value in the range of permitted values.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#min
minLength minlength number -1 The minimum number of characters a user can enter into the text field. Set to -1 for none.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#minlength
noSpinner no-spinner boolean false When true, hide the spinner for type="number" text fields.
pattern pattern string '' A regular expression that the text field's value must match to pass constraint validation.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#pattern
placeholder placeholder string '' Defines the text displayed in the textfield when it has no value. Provides a brief hint to the user as to the expected type of data that should be entered into the control. Unlike label, the placeholder is not visible and does not float when the textfield has a value.https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/placeholder
readOnly readonly boolean false Indicates whether or not a user should be able to edit the text field's value.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly
multiple multiple boolean false Indicates that input accepts multiple email addresses.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email#multiple
step step string '' Returns or sets the element's step attribute, which works with min and max to limit the increments at which a numeric or date-time value can be set.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step
type type TextFieldType | UnsupportedTextFieldType 'text' The type to use, defaults to "text". The type greatly changes how the text field behaves.Text fields support a limited number of types:- text - textarea - email - number - password - search - tel - urlSee https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types for more details on each input type.
autocomplete autocomplete string '' Describes what, if any, type of autocomplete functionality the input should provide.https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
selectionDirection "none" | "forward" | "backward" undefined
selectionEnd number undefined
selectionStart number undefined
valueAsNumber number undefined
valueAsDate Date undefined
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.
validity ValidityState undefined Returns a ValidityState object that represents the validity states of the element.https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
validationMessage string undefined Returns a validation error message or an empty string if the element is valid.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
willValidate boolean undefined Returns whether an element will successfully validate based on forms validation rules and constraints.Disabled and readonly elements will not validate.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate

Methods

Method Parameters Returns Description
select None void Selects all the text in the text field.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select
setRangeText args void
setSelectionRange start, end, direction void Sets the start and end positions of a selection in the text field.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange
showPicker None void Shows the browser picker for an input element of type "date", "time", etc.For a full list of supported types, see: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/showPicker#browser_compatibilityhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/showPicker
stepDown stepDecrement void Decrements the value of a numeric type text field by step or n step number of times.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepDown
stepUp stepIncrement void Increments the value of a numeric type text field by step or n step number of times.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepUp
reset None void Reset the text field to its default value.
formResetCallback None void
formStateRestoreCallback state void
checkValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch an invalid event.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
reportValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch a cancelable invalid event. If not canceled, a the current validationMessage will be reported to the user.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
setCustomValidity error void Sets the element's constraint validation error message. When set to a non-empty string, validity.customError will be true and validationMessage will display the provided error.Use this method to customize error messages reported.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity

Events

Event Type Bubbles Composed Description
select Event Yes No The native select event on ``
change Event Yes No The native change event on ``
input InputEvent Yes Yes The native input event on ``

MdOutlinedTextField `<md-outlined-text-field>`

Properties

Property Attribute Type Default Description
error error boolean false Gets or sets whether or not the text field is in a visually invalid state.This error state overrides the error state controlled by reportValidity().
errorText error-text string '' The error message that replaces supporting text when error is true. If errorText is an empty string, then the supporting text will continue to show.This error message overrides the error message displayed by reportValidity().
label label string '' The floating Material label of the textfield component. It informs the user about what information is requested for a text field. It is aligned with the input text, is always visible, and it floats when focused or when text is entered into the textfield. This label also sets accessibilty labels, but the accessible label is overriden by aria-label.Learn more about floating labels from the Material Design guidelines: https://m3.material.io/components/text-fields/guidelines
noAsterisk no-asterisk boolean false Disables the asterisk on the floating label, when the text field is required.
required required boolean false Indicates that the user must specify a value for the input before the owning form can be submitted and will render an error state when reportValidity() is invoked when value is empty. Additionally the floating label will render an asterisk "*" when true.https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/required
value value string '' The current value of the text field. It is always a string.
prefixText prefix-text string '' An optional prefix to display before the input value.
suffixText suffix-text string '' An optional suffix to display after the input value.
hasLeadingIcon has-leading-icon boolean false Whether or not the text field has a leading icon. Used for SSR.
hasTrailingIcon has-trailing-icon boolean false Whether or not the text field has a trailing icon. Used for SSR.
supportingText supporting-text string '' Conveys additional information below the text field, such as how it should be used.
textDirection text-direction string '' Override the input text CSS direction. Useful for RTL languages that use LTR notation for fractions.
rows rows number 2 The number of rows to display for a type="textarea" text field. Defaults to 2.
cols cols number 20 The number of cols to display for a type="textarea" text field. Defaults to 20.
inputMode inputmode string ''
max max string '' Defines the greatest value in the range of permitted values.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#max
maxLength maxlength number -1 The maximum number of characters a user can enter into the text field. Set to -1 for none.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#maxlength
min min string '' Defines the most negative value in the range of permitted values.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#min
minLength minlength number -1 The minimum number of characters a user can enter into the text field. Set to -1 for none.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#minlength
noSpinner no-spinner boolean false When true, hide the spinner for type="number" text fields.
pattern pattern string '' A regular expression that the text field's value must match to pass constraint validation.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#pattern
placeholder placeholder string '' Defines the text displayed in the textfield when it has no value. Provides a brief hint to the user as to the expected type of data that should be entered into the control. Unlike label, the placeholder is not visible and does not float when the textfield has a value.https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/placeholder
readOnly readonly boolean false Indicates whether or not a user should be able to edit the text field's value.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly
multiple multiple boolean false Indicates that input accepts multiple email addresses.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email#multiple
step step string '' Returns or sets the element's step attribute, which works with min and max to limit the increments at which a numeric or date-time value can be set.https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step
type type TextFieldType | UnsupportedTextFieldType 'text' The type to use, defaults to "text". The type greatly changes how the text field behaves.Text fields support a limited number of types:- text - textarea - email - number - password - search - tel - urlSee https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types for more details on each input type.
autocomplete autocomplete string '' Describes what, if any, type of autocomplete functionality the input should provide.https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
name name string undefined The HTML name to use in form submission.
disabled disabled boolean undefined Whether or not the element is disabled.
selectionDirection "none" | "forward" | "backward" undefined
selectionEnd number undefined
selectionStart number undefined
valueAsNumber number undefined
valueAsDate Date undefined
form HTMLFormElement undefined The associated form element with which this element's value will submit.
labels NodeList undefined The labels this element is associated with.
validity ValidityState undefined Returns a ValidityState object that represents the validity states of the element.https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
validationMessage string undefined Returns a validation error message or an empty string if the element is valid.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
willValidate boolean undefined Returns whether an element will successfully validate based on forms validation rules and constraints.Disabled and readonly elements will not validate.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate

Methods

Method Parameters Returns Description
select None void Selects all the text in the text field.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select
setRangeText args void
setSelectionRange start, end, direction void Sets the start and end positions of a selection in the text field.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange
showPicker None void Shows the browser picker for an input element of type "date", "time", etc.For a full list of supported types, see: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/showPicker#browser_compatibilityhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/showPicker
stepDown stepDecrement void Decrements the value of a numeric type text field by step or n step number of times.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepDown
stepUp stepIncrement void Increments the value of a numeric type text field by step or n step number of times.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/stepUp
reset None void Reset the text field to its default value.
formResetCallback None void
formStateRestoreCallback state void
checkValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch an invalid event.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
reportValidity None boolean Checks the element's constraint validation and returns true if the element is valid or false if not.If invalid, this method will dispatch a cancelable invalid event. If not canceled, a the current validationMessage will be reported to the user.https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
setCustomValidity error void Sets the element's constraint validation error message. When set to a non-empty string, validity.customError will be true and validationMessage will display the provided error.Use this method to customize error messages reported.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity

Events

Event Type Bubbles Composed Description
select Event Yes No The native select event on ``
change Event Yes No The native change event on ``
input InputEvent Yes Yes The native input event on ``

Sass Sass Ext (`docs/sass/sass-ext.md`)

Sass ext

go/sass-ext

A collection of useful Sass modules that extend and complement the functionality
provided by built-in sass:* modules.

Usage

These Sass utilities are intended to reduce boilerplate for common Sass
metaprogramming use cases, such as type checking.

scss
@use '@material/web/sass/ext/assert';
@use '@material/web/sass/ext/map_ext';

@mixin theme($values) {
  $values: assert.is-type($values, 'map');
  --primary: #{map_ext.get-strict($values, 'primary')};
  --secondary: #{map_ext.get-strict($values, 'secondary')};
  --tertiary: #{map_ext.get-strict($values, 'tertiary')};
}

The same logic using built-in modules requires more boilerplate.

scss
@use 'sass:map';
@use 'sass:meta';

@mixin theme($values) {
  @if meta.type-of($values) != 'map' {
    @error 'Argument is not a map: #{meta.inspect($values)}';
  }
  @if not map.has-key($values, 'primary') {
    @error 'Map is missing key "primary": #{meta.inspect($values)}';
  }
  @if not map.has-key($values, 'secondary') {
    @error 'Map is missing key "secondary": #{meta.inspect($values)}';
  }
  @if not map.has-key($values, 'tertiary') {
    @error 'Map is missing key "tertiary": #{meta.inspect($values)}';
  }

  --primary: #{map.get($values, 'primary')};
  --secondary: #{map.get($values, 'secondary')};
  --tertiary: #{map.get($values, 'tertiary')};
}

Who should use `sass/ext`?

These utilities should be used by Sass libraries that need to perform
repetitive and complex Sass metaprogramming logic.

Prefer using built-in Sass functionality for simple use cases where sass/ext
would not reduce complexity.

scss {.bad}
// Using sass/ext here does not reduce boilerplate, and adds another API to
// learn and maintain.
@use '@material/web/sass/ext/type';

@function value-or-default($value, $default) {
  @if type.matches($value, 'null') {
    @return $default;
  }
  @return $value;
}
scss {.good}
// For simple use cases, built-in Sass functionality should be preferred.
@function value-or-default($value, $default) {
  @if $value == null {
    @return $default;
  }
  @return $value;
}

`assert`

`is-type` {#assert.is-type}

scss
assert.is-type($arg, $type, $message, $source)

/// @param {*} $arg - The argument to check.
/// @param {string} $type - The string type to assert the argument matches. Multiple types may be separated by '|'.
/// @param {string} $message - Optional custom error message.
/// @param {string} $source - Optional source of the error message.
/// @return {*} The argument if it matches the type string.
/// @throw Error if the argument does not match the type string.

Asserts that the argument is a specific type. If it is, the argument is
returned, otherwise an error is thrown.

scss
@mixin multiply($a, $b) {
  $a: assert.is-type($a, 'number');
  $b: assert.is-type($b, 'number');
  @return $a * $b;
}

@function is-empty($value) {
  $value: assert.is-type(
    $value,
    'list|map|null',
    $message: '$value must be a list, map, or null',
    $source: 'is-empty'
  );
  @return $value and list.length($value) == 0;
}

`not-type` {#assert.not-type}

scss
assert.not-type($arg, $type, $message, $source)

/// @param {*} $arg - The argument to check.
/// @param {string} $type - The string type to assert the argument does not match. Multiple types may be separated by '|'.
/// @param {string} $message - Optional custom error message.
/// @param {string} $source - Optional source of the error message.
/// @return {*} The argument if it does not match the type string.
/// @throw Error if the argument matches the type string.

Asserts that the argument is not a specific type. The argument is returned
if it does not match. An error is thrown if the argument matches the type.

scss
@function get-strict($map, $key) {
  @return assert.not-type(
    map.get($map, $key),
    'null',
    $message: 'Key must be in the map'
  );
}

`list_ext`

`difference` {#list_ext.difference}

scss
list_ext.difference($listA, $listB) //=> list

/// @param {list} $listA - The first list to compare.
/// @param {list} $listB - The second list to compare.
/// @return {list} All items in $listA that are not in $listB.

Returns the difference between two lists.

scss
$listA: ('apple', 'banana', 'cherry', 'date');
$listB: ('banana', 'cherry', 'apple');
$listC: ('apple', 'banana', 'date');

@debug list_ext.difference($listA, $listB); // ('date')
@debug list_ext.difference($listA, $listC); // ('cherry')

`are-equal` {#list_ext.are-equal}

scss
list_ext.are-equal($listA, $listB) //=> boolean

/// @param {list} $listA - The first list to compare.
/// @param {list} $listB - The second list to compare.
/// @return {boolean} `true` if the lists contain the same elements, otherwise `false`.

Checks if two lists contain the same elements, regardless of their order.

The function iterates through each list and verifies that every element in
one list is present in the other. The order of elements does not affect the
result.

scss
$listA: ('apple', 'banana', 'cherry');
$listB: ('banana', 'cherry', 'apple');
$listC: ('apple', 'banana', 'date');

@debug list_ext.are-equal($listA, $listB); // true
@debug list_ext.are-equal($listA, $listC); // false

`intersection` {#list_ext.intersection}

scss
list_ext.intersection($listA, $listB) //=> list

/// @param {list} $listA - The first list to compare.
/// @param {list} $listB - The second list to compare.
/// @return {list} All items in $listA that are also in $listB.

Returns the intersection of two lists.

scss
$listA: ('apple', 'banana', 'cherry', 'date');
$listB: ('banana', 'cherry', 'apple');
$listC: ('apple', 'banana', 'date');

@debug list_ext.intersection($listA, $listB); // ('apple', 'banana', 'cherry')
@debug list_ext.intersection($listA, $listC); // ('apple', 'banana')

`map_ext`

`get-strict` {#map_ext.get-strict}

scss
map_ext.get-strict($map, $key, $keys)

/// @param {map} $map - The map to retrieve the value from.
/// @param {string} $key - The key of the value to retrieve.
/// @param {list} $keys - Additional keys to retrieve deeply nested values.
/// @return {*} The value at the given key.
/// @throw Error if the key does not exist in the map.

The same as map.get() but throws an error if the key is not found.

This is useful over map.get() when using Sass maps like records, where
the key is expected to exist.

scss
$map: (
  'name': 'foo',
  'value': blue,
);

@debug map_ext.get-strict($map, 'name'); // 'foo'
@debug map_ext.get-strict($map, 'bar'); // ERROR: Key "bar" expected but not found in $map: ('name': 'foo', 'value': blue)

`split` {#map_ext.split}

scss
map_ext.split($map, $keys) //=> list

/// @param {map} $map - The Map to split.
/// @param {list} $keys - List of keys to split the Map by.
/// @return {list} A List pair with two new Maps: the first with the keys provided, and the second with the remaining keys.

Splits a Map and returns a List pair with two new Maps: the first with the
provided keys and the second without.

scss
$map: (
  'focus': blue,
  'focus-within': blue,
  'hover': teal,
  'active': green,
);

$pair: map_ext.split($map, ('focus', 'focus-within'));

$map-with-focus-keys: list.nth($pair, 1);
@debug $map-with-focus-keys; // ('focus': blue, 'focus-within': blue)

$map-with-remaining-keys: list.nth($pair, 2);
@debug $map-with-remaining-keys; // ('hover': teal, 'active': green)

`pick` {#map_ext.pick}

scss
map_ext.pick($map, $keys) //=> map

/// @param {map} $map - The Map to split.
/// @param {list} $keys - List of keys to include in the new Map.
/// @return {map} Map with only the keys provided.

Splits a Map and returns a new Map that only includes the provided keys.

scss
$map: (
  'focus': blue,
  'focus-within': blue,
  'hover': teal,
  'active': green,
);

$map-with-focus-keys: map_ext.pick($map, ('focus', 'focus-within'));
@debug $map-with-focus-keys; // ('focus': blue, 'focus-within': blue)

`omit` {#map_ext.omit}

scss
map_ext.omit($map, $keys) //=> map

/// @param {map} $map - The Map to split.
/// @param {list} $keys - List of keys to exclude from the new Map.
/// @return {map} Map without the keys provided.

Splits a Map and returns a new Map that excludes the provided keys.

scss
$map: (
  'focus': blue,
  'focus-within': blue,
  'hover': teal,
  'active': green,
);

$map-without-focus-keys: map_ext.omit($map, ('focus', 'focus-within'));
@debug $map-without-focus-keys; // ('hover': teal, 'active': green)

`rename-keys` {#map_ext.rename-keys}

scss
map_ext.rename-keys($map, $keys-to-rename) //=> map

/// @param {map} $map - The map to rename keys within.
/// @param {map} $keys-to-rename - A map of keys and their new names.
/// @return {map} The map with any matching keys renamed.

Returns the given map with any matching keys renamed according to the
provided Map of keys to rename.

scss
$map: ('foo': red);

$new-map: map_ext.rename-keys($map, ('foo': 'bar'));
@debug $new-map; // ('bar': red)

`difference` {#map_ext.difference}

scss
map_ext.difference($mapA, $mapB) //=> list

/// @param {map} $mapA - The reference map.
/// @param {map} $mapB - The map to compare against the reference.
/// @return {list} A list of keys where $mapB diverges from $mapA.

Returns a list of keys where $mapB diverges from $mapA.
Divergence occurs when:

  1. A key exists in $mapB but not in $mapA.
  2. A key exists in both maps but with different values.
scss
$mapA: ('foo': red, 'bar': yellow, 'baz': 10);
$mapB: ('foo': red, 'bar': green,  'baz': 10, 'fooBar': blue);

$differences: map_ext.difference($mapA, $mapB);
@debug $differences; // ('bar', 'fooBar')

`string_ext`

`starts-with` {#string_ext.starts-with}

scss
string_ext.starts-with($string, $prefix) //=> boolean

/// @param {string} $string - The string to test.
/// @param {string} $prefix - The prefix to check.
/// @return {boolean} True if the string starts with the given prefix.

Checks if a string starts with a given prefix.

scss
@debug string_ext.starts-with('var(--foo)', 'var('); // true

`ends-with` {#string_ext.ends-with}

scss
string_ext.ends-with($string, $suffix) //=> boolean

/// @param {string} $string - The string to test.
/// @param {string} $suffix - The suffix to check.
/// @return {boolean} True if the string ends with the given suffix.

Checks if a string ends with a given suffix.

scss
@debug string_ext.ends-with('var(--foo)', ')'); // true

`trim-start` {#string_ext.trim-start}

scss
string_ext.trim-start($string) //=> string

/// @param {string} $string - The string to trim.
/// @return {string} The string with whitespace trimmed from the start.

Trims leading whitespace from the start of a string.

scss
@debug string_ext.trim-start('  foo bar  '); // "foo bar  "

`trim-end` {#string_ext.trim-end}

scss
string_ext.trim-end($string) //=> string

/// @param {string} $string - The string to trim.
/// @return {string} The string with trailing whitespace trimmed from the end.

Trims trailing whitespace from the end of a string.

scss
@debug string_ext.trim-end('  foo bar  '); // "  foo bar"

`trim` {#string_ext.trim}

scss
string_ext.trim($string) //=> string

/// @param {string} $string - The string to trim.
/// @return {string} The string with leading and trailing whitespace trimmed.

Trims leading and trailing whitespace from a string.

scss
@debug string_ext.trim('  foo bar  '); // "foo bar"

`replace` {#string_ext.replace}

scss
string_ext.replace($string, $pattern, $replacement) //=> string

/// @param {string} $string - The string to be searched.
/// @param {string} $pattern - The pattern to search for.
/// @param {string} $replacement - The value to replace the pattern.
/// @return {string} The string with the first match of pattern replaced by the replacement or the initial string itself.

Returns a new string with the first match of a pattern replaced by a given
string.

scss
@debug string_ext.replace('foo bar baz', 'bar', 'quux'); // "foo quux baz"

`replace-all` {#string_ext.replace-all}

scss
string_ext.replace-all($string, $pattern, $replacement) //=> string

/// @param {string} $string - The string to be searched.
/// @param {string} $pattern - The pattern to search for.
/// @param {string} $replacement - The value to replace the pattern.
/// @return {string} The string with all matches of pattern replaced by the replacement or the initial string itself.

Returns a new string with all matches of a pattern replaced by a given
string.

scss
@debug string_ext.replace-all('foo bar baz', 'ba', 'qua'); // "foo quar quaz"

`replace-start` {#string_ext.replace-start}

scss
string_ext.replace-start($string, $prefix, $replacement) //=> string

/// @param {string} $string - The string to be searched.
/// @param {string} $prefix - The prefix string to replace.
/// @param {string} $replacement - The value to replace the prefix.
/// @return {string} The string with the prefix replaced.

Returns a new string that replaces a prefix at the start of the string.

scss
@debug string_ext.replace-start('var(--foo)', 'var(', ''); // "--foo)"

`replace-end` {#string_ext.replace-end}

scss
string_ext.replace-end($string, $suffix, $replacement) //=> string

/// @param {string} $string - The string to be searched.
/// @param {string} $suffix - The suffix string to replace.
/// @param {string} $replacement - The value to replace the suffix.
/// @return {string} The string with the suffix trimmed from the end.

Returns a new string that replaces a suffix at the end of the string.

scss
@debug string_ext.replace-end('var(--foo)', ')', ''); // "var(--foo"

`throw`

`get-error` {#throw.get-error}

scss
throw.get-error($error, $errors)

/// @param {*} $error - The value to check.
/// @param {list} $errors - Additional values to check. Useful for checking multiple errors at the same time.
/// @return {string|boolean} The error string if any value is an error, or false otherwise.

Returns false if none of the given values are error strings, or returns an
error string if any value has an error.

This is used to support testing error behavior with sass-true, since
@error messages cannot be caught at build time.

scss
// A function that may return an "ERROR:" string in a test.
@function get-value($map, $key) {
  @if meta.type-of($map) != 'map' {
    // Identical to `@error 'ERROR: Arg is not a map'` outside of tests.
    @return throw.error('Arg is not a map');
  }
  @return map.get($map, $key);
}

// A function that needs to handle potential errors from other functions.
@function mix-primary-on-surface($values) {
  $primary: get-value($values, 'primary');
  $surface: get-value($values, 'surface');
  $error: throw.get-error($primary, $surface);
  @if $error {
    // Return early to guard logic against additional errors since
    // $primary or $surface may be a string instead of a color.
    @return $error;
  }

  @return color.mix($primary, $surface, 10%);
}

Note: throw.error() and throw.get-error() are only useful when testing
error behavior using sass-true. If you are not testing a function, use
@error instead.

scss
// In a `sass-true` test, `throw.get-error()` can be used to assert that
// an error is thrown.
@use 'true' as test with ($catch-errors: true);

@include test.describe('module.get-value()') {
  @include test.it('throws an error if the value is not a map') {
    $result: module.get-value('not a map', 'primary');
    @include test.assert-truthy(throw.get-error($result), '$result is an error');
  }
}

`type`

`matches` {#type.matches}

scss
type.matches($value, $type-string) //=> boolean

/// @param {*} $value - The value to check the type of.
/// @param {string} $type-string - The type to check. May be multiple types separated by `|`.
/// @return {boolean} True if the value matches the type string.

Returns true if the given value matches the provided type string.

The type string supports multiple types separated by |, such as
'string|null'. Type options are any values returned by meta.type-of().

scss
@function is-empty($value) {
  @if type.matches($value, 'list|map') {
    @return list.length($value) == 0;
  }
  @if type.matches($value, 'string') {
    @return $value == '';
  }
  @return type.matches($value, 'null');
}

`var`

`create` {#var.create}

scss
var.create($name, $fallback) //=> string

/// @param {string} $name - The name of the custom property.
/// @param {*} $fallback [null] - Optional `var()` fallback value.
/// @return {string} A custom property `var()` string.

Creates a custom property var() string.

scss
@debug var.create(--foo); // "var(--foo)"
@debug var.create(--foo, 8px); // "var(--foo, 8px)"

`name` {#var.name}

scss
var.name($var) //=> string

/// @param {string} $var - A custom property `var()` string.
/// @return {string} The custom property variable name.
/// @throw If the value is not a custom property.

Returns the custom property variable name of var() string.

scss
$var: var(--foo);
@debug var.name($var); // "--foo"

`fallback` {#var.fallback}

scss
var.fallback($var) //=> string

/// @param {string} $var - A custom property `var()` string.
/// @return {string} The fallback value of the `var()` string. May be null if the `var()` does not have a fallback value.
/// @throw If the value is not a custom property.

Returns the fallback value of a custom property var() string. The value
may be null if the var() does not have a fallback value.

scss
$var: var(--foo, var(--bar, 8px));
@debug var.fallback($var); // "var(--bar, 8px)"

`deep-fallback` {#var.deep-fallback}

scss
var.deep-fallback($var) //=> string

/// @param {string} $var - A custom property `var()` string.
/// @return {string} The deep fallback value of the `var()` string. May be null if the `var()` does not have a fallback value.
/// @throw If the value is not a custom property.

Returns the deep fallback value of a custom property var() string. The
value may be null if the var() does not have a fallback value.

If a fallback value is another var(), this function will return the final
concrete value in the chain.

scss
$var: var(--foo, var(--bar, 8px));
@debug var.deep-fallback($var); // "8px"

`set-fallback` {#var.set-fallback}

scss
var.set-fallback($var, $new-fallback) //=> string

/// @param {string} $var - A custom property `var()` string.
/// @param {*} $new-fallback - The new fallback value. May be null to remove a value.
/// @return {string} A custom property `var()` string with the new fallback value.
/// @throw If the value is not a custom property.

Creates a new custom property var() string and returns it with the
specified new fallback value.

scss
$var: var(--foo, var(--bar, 8px));
$new-var: set-fallback($var, 16px);
@debug $new-var; // "var(--foo, 16px)"

`deep-set-fallback` {#var.deep-set-fallback}

scss
var.deep-set-fallback($var, $new-fallback) //=> string

/// @param {string} $var - A custom property `var()` string.
/// @param {*} $new-fallback - The new fallback value. May be null to remove a value.
/// @return {string} A custom property `var()` string with the new deep fallback value.
/// @throw If the value is not a custom property.

Creates a new custom property var() string and returns it with the
specified new deep fallback value.

If the provided var() string's fallback value is another var(), this
function will set the final fallback value in the chain.

scss
$var: var(--foo, var(--bar, 8px));
$new-var: var.deep-set-fallback($var, 16px);
@debug $new-var; // "var(--foo, var(--bar, 16px))"

`is-var` {#var.is-var}

scss
var.is-var($var) //=> boolean

/// @param {*} $var - The value to test.
/// @return {boolean} True if the value is a custom property `var()` string, or false if not.

Indicates whether or not a value is a custom property var() string.

scss
$var: var(--foo);
@debug var.is-var($var); // true

Theming Color (`docs/theming/color.md`)

Color

Color creates meaning
and communicates hierarchy, state, and brand.

Color scheme

A
color scheme
is the group of
key color tones
assigned to specific roles that get mapped to components.

Tip: use the
Material theme builder Figma plugin
to generate a color scheme.

Alternatively, use the
material-color-utilities library
to generate color schemes at runtime.

Tokens

A color scheme can be set using
CSS custom properties.
Tokens follow the naming convention --md-sys-color-<token>.

All tokens have a corresponding --md-sys-color-on-<token> for content color
with accessible contrast.

Key color Tokens
Primary --md-sys-color-primary
  --md-sys-color-primary-container
Secondary --md-sys-color-secondary
  --md-sys-color-secondary-container
Tertiary --md-sys-color-tertiary
  --md-sys-color-tertiary-container
Error --md-sys-color-error
  --md-sys-color-error-container
Neutral --md-sys-color-background
  --md-sys-color-surface
  --md-sys-color-surface-bright *
  --md-sys-color-surface-dim *
  --md-sys-color-surface-container *
  --md-sys-color-surface-container-lowest *
  --md-sys-color-surface-container-low *
  --md-sys-color-surface-container-high *
  --md-sys-color-surface-container-highest *
  --md-sys-color-outline
  --md-sys-color-outline-variant

* all surface tokens use --md-sys-color-on-surface or
--md-sys-color-on-surface-variant for their content.

css
:root {
  /* Generated from Material Theme Builder Figma plugin
     or `material-color-utilities`. */
  --md-sys-color-primary: #006A6A;
  --md-sys-color-on-primary: #FFFFFF;
  --md-sys-color-primary-container: #6FF7F6;
  --md-sys-color-on-primary-container: #002020;
  /* ... */
}

/* Usage in custom components */
.primary {
  background: var(--md-sys-color-primary);
  color: var(--md-sys-color-on-primary);
}

Theming Shape (`docs/theming/shape.md`)

Shape

Shape can direct attention,
communicate state, and express brand.

Shape

Corners use a
range of shape scales
for their roundness, from straight to fully round.

Note: "cut" corners are not supported.

Tokens

Shape corners can be set using
CSS custom properties.
Tokens follow the naming convention --md-sys-shape-<token>.

Shape Token
Corner --md-sys-shape-corner-none
  --md-sys-shape-corner-extra-small
  --md-sys-shape-corner-small
  --md-sys-shape-corner-medium
  --md-sys-shape-corner-large
  --md-sys-shape-corner-extra-large
  --md-sys-shape-corner-full
css
:root {
  --md-sys-shape-corner-small: 4px;
  --md-sys-shape-corner-medium: 6px;
  --md-sys-shape-corner-large: 8px;
}

Theming Typography (`docs/theming/typography.md`)

Typography

Typography helps make
writing legible and beautiful.

Tip: "typeface" and "typescale" can be confusing. "face" refers to
font-family and font-weight.

"scale" refers to a group of font-family, font-size, line-height, and
font-weight tokens.

Typeface

A typeface is a
font-family. In Material there are plain and brand typefaces.

Each typeface has normal, medium, and bold styles (defaults to 400, 500, and
700). All three weight styles need to be included for a font.

Important: if you do not change the typeface, be sure to load the default
'Roboto' font. For example, from
fonts.google.com.

Tokens

Typefaces can be set using
CSS custom properties.
Tokens follow the naming convention --md-ref-typeface-<token>.

Typeface Token
Brand --md-ref-typeface-brand
Plain --md-ref-typeface-plain
css
@import url('https://fonts.googleapis.com/css2?family=Open%20Sans:wght@400;500;700&display=swap');

:root {
  --md-ref-typeface-brand: 'Open Sans';
  --md-ref-typeface-plain: system-ui;
}

Typescale

A
typescale
is a collection of font styles: font-family, font-size, line-height, and
font-weight. They are organized into roles that describe their purpose.

Material's
applying type guidelines
explains when to use each typescale role.

Classes

Typescales can be applied to an element using the classes from the typescale
stylesheet.

Class names follow the naming convention .md-typescale-<scale>-<size>.

ts
import {styles as typescaleStyles} from '@material/web/typography/md-typescale-styles.js';

// `typescaleStyles.styleSheet` is a `CSSStyleSheet` that can be added to a
// document or shadow root's `adoptedStyleSheets` to use the `.md-typescale-*`
// classes.
document.adoptedStyleSheets.push(typescaleStyles.styleSheet);

// `typescaleStyles` can also be added to a `LitElement` component's styles.
class App extends LitElement {
  static styles = [typescaleStyles, css`...`];

  render() {
    return html`
      <h1 class="md-typescale-display-large">Large display</h1>
      <p class="md-typescale-body-medium">Body text</p>
    `;
  }
}

Tokens

Typescales can be set using
CSS custom properties.
Each typescale has three sizes: small, medium, and large. Each size has
four properties: font (family), size, line-height, and weight.

Tokens follow the naming convention
--md-sys-typescale-<scale>-<size>-.

Typescale Tokens
Display --md-sys-typescale-display-medium-font
  --md-sys-typescale-display-medium-size
  --md-sys-typescale-display-medium-line-height
  --md-sys-typescale-display-medium-weight
Headline --md-sys-typescale-headline-medium-font
  --md-sys-typescale-headline-medium-size
  --md-sys-typescale-headline-medium-line-height
  --md-sys-typescale-headline-medium-weight
Title --md-sys-typescale-title-medium-font
  --md-sys-typescale-title-medium-size
  --md-sys-typescale-title-medium-line-height
  --md-sys-typescale-title-medium-weight
Body --md-sys-typescale-body-medium-font
  --md-sys-typescale-body-medium-size
  --md-sys-typescale-body-medium-line-height
  --md-sys-typescale-body-medium-weight
Label --md-sys-typescale-label-medium-font
  --md-sys-typescale-label-medium-size
  --md-sys-typescale-label-medium-line-height
  --md-sys-typescale-label-medium-weight
css
:root {
  --md-sys-typescale-body-medium-size: 1rem;
  --md-sys-typescale-body-medium-line-height: 1.5rem;
  /* ... */
}

Tip: to change all font families across typescales, prefer setting
--md-ref-typeface-brand and --md-ref-typeface-plain, which map to each
typescale.

Use --md-sys-typescale-<scale>-<size>-font to change the typeface that a
font is mapped to. This is useful for custom typefaces.

css
:root {
  --my-brand-font: 'Open Sans';
  --my-headline-font: 'Montserrat';
  --my-title-font: 'Montserrat';
  --my-plain-font: system-ui;

  --md-ref-typeface-brand: var(--my-brand-font);
  --md-ref-typeface-plain: var(--my-plain-font);

  --md-sys-typescale-headline-font: var(--my-headline-font);
  --md-sys-typescale-title-font: var(--my-title-font);
}

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#component- Browse component- catalog → #design-system Browse design-system catalog → #lit Browse lit catalog → #lit-element Browse lit-element catalog → #lit-html Browse lit-html catalog → #material Browse material catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →