# Technical Documentation: material-components/material-web

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/material-components/material-web)

### Overview (`README.md`)

# Material Web

<img src="./docs/images/material-web.gif"
  title="Material web components"
  alt="A collection of Material web components"
  style="border-radius: 32px">

[](https://www.npmjs.com/package/@material/web)
[](https://lit.dev/discord/)
[](https://github.com/material-components/material-web/actions/workflows/test.yml)
[](https://npm-stat.com/charts.html?package=%40material%2Fweb)
[](https://www.jsdelivr.com/package/npm/@material/web?tab=stats)

`@material/web` is a library of
[web components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
that helps build beautiful and accessible web applications. It uses
[Material 3](https://m3.material.io/), the latest version of Google's
open-source design system.

**Note:
[MWC is in maintenance mode pending new maintainers](https://github.com/material-components/material-web/discussions/5642).**

## Resources

-   [Introduction](./docs/intro.md)
-   [Roadmap](./docs/roadmap.md)
-   [Component docs](./docs/components/)
-   [Bundle size](./docs/size.md)
-   [Browser support and FAQ](./docs/support.md)

## Quick start

> Tip: Using Angular? We recommend using
> [Angular Material](https://material.angular.io/) components
> instead.

This code snippet is a buildless example that loads `@material/web` from a CDN.
Check out the [quick start](./docs/quick-start.md) 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](https://m3.material.io/foundations/customization)
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 for
a green primary color flows through system UI
harmoniously](images/theming.webp "A user-generated color scheme can flow through apps that use a custom theme.")

## Tokens

Material is expressed in
[design tokens](https://m3.material.io/foundations/design-tokens/overview),
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 to
reference
tokens](images/token-types.webp "The relationship between reference, system, and component tokens.")

On the web, design tokens are
[CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)
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](typography.md#typeface) 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](color.md#tokens) define dynamic color roles that map
to components. See the [color guide](color.md) for more details.

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

#### Typography

[`--md-sys-typescale` tokens](typography.md#typescale) define typescale roles
that map to components. See the [typography guide](typography.md) 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](shape.md#tokens) define corner shapes used in
components. See the [shape guide](shape.md) 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](../components/) 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 | `<span class="tab-label">` | `slot="label"` | Required. Bare text is not supported. |
| Badge | `<span class="badge tab-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>
```

### `<md-gb-tabs>`

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

### `<md-gb-tab>`

| 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. `<span class="badge tab-badge">`). |

#### 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](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
that follows Google's [Material Design](https://material.io/)
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](https://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](https://developer.mozilla.org/en-US/docs/Web/API/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 `<button>` and `<input>`.

```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](https://m3.material.io/foundations/design-tokens/overview)
are the building blocks of all UI elements. In MWC, tokens are
[CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)
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](https://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](#install) and [build](#building) steps
below.

## Install



Install Material web components using
[npm and node](https://nodejs.org).

```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](components/) for more guidance on using each component.

[Playground](https://lit.dev/playground/#gist=37d28012c5ec6de30809bdf4a6e26cb6)

```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](https://github.com/WICG/import-maps) are
adopted.

We recommend following
[lit.dev's modern build for production](https://lit.dev/docs/tools/production/#modern-only-build)
for a more in-depth build guide.

### Rollup quick start

For a quick start, we recommend using [Rollup](https://rollupjs.org/)
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](https://github.com/material-components/material-web/discussions/5642)
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](https://github.com/material-components/material-web/discussions/5642).**
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](https://www.typescriptlang.org/docs/handbook/jsx.html) is a popular
language extension for frameworks like [React](https://reactjs.org/). 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](https://m3.material.io/foundations/layout/understanding-layout/overview).

## 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*

*   Components
    *   ✅
        [Card preview](https://github.com/material-components/material-web/tree/c9360e2310dee2896592649f8a8f9b03e2737bf2/labs/card)
*   Features
    *   🟡 Prevent event default behavior
        *   *We fixed lots of bugs, but there's still ways we can improve.*
    *   ✅
        [Size tracking](https://github.com/material-components/material-web/blob/c9360e2310dee2896592649f8a8f9b03e2737bf2/docs/size.md)
    *   ✅ [Docs and examples](https://material-web.dev/)

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




<sub>Last updated 2025-08-20.</sub>



| 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](https://www.npmjs.com/package/element-internals-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?](#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](https://www.figma.com/community/plugin/1034969338659738588/Material-Theme-Builder)
    to generate a color scheme.

-   Use the
    [`material-color-utilities` library](https://www.npmjs.com/package/@material/material-color-utilities)
    to generate color schemes at runtime.

### How do I customize an `<md-*>` element that is inside another component?

Use [CSS `::part()`s](https://developer.mozilla.org/en-US/docs/Web/CSS/::part)
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`)

<catalog-component-header>
<catalog-component-header-title slot="title">

# Buttons










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/button/).**




[Buttons](https://m3.material.io/components/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.

</catalog-component-header-title>

<img
    class="hero"
    alt="A phone showing a payment screen with a green filled button that says 'Make
payment'"
    title="There are 5 types of common buttons"
    src="images/button/hero.webp">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/buttons) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/button)
    







## Types












1.  [Elevated button](#elevated-button)
1.  [Filled button](#filled-button)
1.  [Filled tonal button](#filled-tonal-button)
1.  [Outlined button](#outlined-button)
1.  [Text button](#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"](images/button/usage.webp "Outlined and filled buttons.")








```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 button
with the text 'open' with a trailing icon arrow
box](images/button/usage-icon.webp "Slot in icons to the appropriate slots")








```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`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_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](https://m3.material.io/components/buttons/guidelines#4e89da4d-a8fa-4e20-bb8d-b8a93eff3e3e)
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](https://m3.material.io/components/buttons/guidelines#9ecffdb3-ef29-47e7-8d5d-f78b404fcafe)
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](https://m3.material.io/components/buttons/guidelines#07a1577b-aaf5-4824-a698-03526421058b)
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](https://m3.material.io/components/buttons/guidelines#3742b09f-c224-43e0-a83e-541bd29d0f05)
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](https://m3.material.io/components/buttons/guidelines#c9bcbc0b-ee05-45ad-8e80-e814ae919fbb)
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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-elevated-button.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-filled-button.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-filled-tonal-button.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-outlined-button.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-text-button.scss)
    

### 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 <code>&lt;md-elevated-button&gt;</code>

#### Properties



| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `softDisabled` | `soft-disabled` | `boolean` | `false` | Whether or not the button is "soft-disabled" (disabled but still focusable).<br>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.<br>_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.<br>- 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 <code>&lt;md-filled-button&gt;</code>

#### Properties



| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `softDisabled` | `soft-disabled` | `boolean` | `false` | Whether or not the button is "soft-disabled" (disabled but still focusable).<br>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.<br>_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.<br>- 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 <code>&lt;md-filled-tonal-button&gt;</code>

#### Properties



| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `softDisabled` | `soft-disabled` | `boolean` | `false` | Whether or not the button is "soft-disabled" (disabled but still focusable).<br>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.<br>_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.<br>- 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 <code>&lt;md-outlined-button&gt;</code>

#### Properties



| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `softDisabled` | `soft-disabled` | `boolean` | `false` | Whether or not the button is "soft-disabled" (disabled but still focusable).<br>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.<br>_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.<br>- 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 <code>&lt;md-text-button&gt;</code>

#### Properties



| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `softDisabled` | `soft-disabled` | `boolean` | `false` | Whether or not the button is "soft-disabled" (disabled but still focusable).<br>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.<br>_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.<br>- 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`)

<catalog-component-header>
<catalog-component-header-title slot="title">

# Checkbox










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/checkbox/).**




[Checkboxes](https://m3.material.io/components/checkbox) 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.

</catalog-component-header-title>

<img
    class="hero"
    src="images/checkbox/hero.webp"
    alt="A list of burger additions represented with checkboxes"
    title="Checkboxes in a list of items.">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/checkbox) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/checkbox)
    







## 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`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-checkbox.scss)
    

### 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 <code>&lt;md-checkbox&gt;</code>

#### 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.<br>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.<br>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.<br>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.<br>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.<br>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.<br>Disabled and readonly elements will not validate.<br>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.<br>If invalid, this method will dispatch an `invalid` event.<br>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.<br>If invalid, this method will dispatch a cancelable `invalid` event. If not canceled, a the current `validationMessage` will be reported to the user.<br>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.<br>Use this method to customize error messages reported.<br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity |



#### Events



| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `change` | `Event` | Yes | No | The native `change` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) |
| `input` | `InputEvent` | Yes | Yes | The native `input` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) |

---

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

<catalog-component-header image-align="start">
<catalog-component-header-title slot="title">

# Chips










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/chip/)**




[Chips](https://m3.material.io/components/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.

</catalog-component-header-title>

<img class="hero" src="images/chips/hero.webp" alt="Two collections of filter chips, with some options selected and some unselected."
title="Filter chips">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/chips) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/chips)
    

## Types

1.  [Assist chip](#assist-chip)
1.  [Filter chip](#filter-chip)
1.  [Input chip](#input-chip)
1.  [Suggestion chip](#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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role)
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`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label)
attribute to chip sets or reference a label with
[`aria-labelledby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_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](https://m3.material.io/components/chips/guidelines#5dd1928c-1476-4029-bdc5-fde66fc0dcb1)
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](https://m3.material.io/components/chips/guidelines#8d453d50-8d8e-43aa-9ae3-87ed134d2e64)
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](https://m3.material.io/components/chips/guidelines#4d2d5ef5-3fcd-46e9-99f2-067747b2393f)
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](https://m3.material.io/components/chips/guidelines#36d7bb16-a9bf-4cf6-a73d-8e05510d66a7)
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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-assist-chip.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-filter-chip.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-input-chip.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-suggestion-chip.scss)
    

### 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 <code>&lt;md-chip-set&gt;</code>

#### Properties



| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `chips` |  | `Chip[]` | `undefined` |  |



### MdAssistChip <code>&lt;md-assist-chip&gt;</code>

#### 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.<br>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).<br>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.<br>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.<br>Add this attribute when a chip has a `slot="icon"` to avoid a Flash Of Unstyled Content. |



#### Events



| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `update-focus` | `Event` | Yes | No | Dispatched when `disabled` is toggled. |



### MdFilterChip <code>&lt;md-filter-chip&gt;</code>

#### 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.<br>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.<br>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).<br>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.<br>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.<br>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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `remove` | `Event` | No | No | Dispatched when the remove button is clicked. |
| `update-focus` | `Event` | Yes | No | Dispatched when `disabled` is toggled. |



### MdInputChip <code>&lt;md-input-chip&gt;</code>

#### 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.<br>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).<br>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.<br>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.<br>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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `remove` | `Event` | No | No | Dispatched when the remove button is clicked. |
| `update-focus` | `Event` | Yes | No | Dispatched when `disabled` is toggled. |



### MdSuggestionChip <code>&lt;md-suggestion-chip&gt;</code>

#### 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.<br>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).<br>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.<br>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.<br>Add this attribute when a chip has a `slot="icon"` to avoid a Flash Of Unstyled Content. |



#### Events



| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `update-focus` | `Event` | Yes | No | Dispatched when `disabled` is toggled. |

---

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

<catalog-component-header image-align="start">
<catalog-component-header-title slot="title">

# Dialogs










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/dialog/)**




[Dialogs](https://m3.material.io/components/dialogs) provide
important prompts in a user flow.

</catalog-component-header-title>

<img class="hero" src="images/dialog/hero.webp" alt="A dialog displaying phone ringtone options."
title="A dialog">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/dialogs) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/dialog)
    







## Usage

Dialogs behave like
[`<dialog>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement)
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`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role)
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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-dialog.scss)
    

### 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 <code>&lt;md-dialog&gt;</code>

#### 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.<br>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.<br>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).<br>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.<br>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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/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](https://m3.material.io/components/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.



*   [Design article](https://m3.material.io/components/divider) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/divider)
    

## 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"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/separator_role)
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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-divider.scss)
    

### 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 <code>&lt;md-divider&gt;</code>

#### 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](https://m3.material.io/styles/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.



*   [Design article](https://m3.material.io/styles/elevation) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/elevation)
    

## 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 square
lowers into the background and the shadow disappears, then
repeats.](images/elevation/usage-animation.gif "Animating between elevations.")

```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](../theming/README.md) and can be
customized in terms of color.

### Tokens

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

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-elevation.scss)
    

### 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`)

<catalog-component-header>
<catalog-component-header-title slot="title">

# Floating action buttons (FAB)










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/fab/).**




[FAB](https://m3.material.io/components/floating-action-button)
represents the most important action on a screen. It puts key actions within
reach.

[Extended FABs](https://m3.material.io/components/extended-fab) help people take
primary actions. They're wider than FABs to accommodate a text label and larger
target area.

</catalog-component-header-title>

<img
    class="hero"
    alt="A phone showing a payment screen with a green filled button that says 'Make
payment'"
    src="images/fab/hero.webp">

</catalog-component-header>

*   Design articles
    *   [FAB](https://m3.material.io/components/floating-action-button)
        
    *   [Extended FAB](https://m3.material.io/components/extended-fab)
        
*   API Documentation (*coming soon*)
*   [Source code](https://github.com/material-components/material-web/tree/main/fab)
    







## Types








1.  [FAB](#fab)
2.  [Small FAB](#sizes)
3.  [Large FAB](#sizes)

### Extended FAB








*   [Extended FAB with both icon and label text](#extended)
*   [API Documentation](#api)
*   [Extended FAB without icon](#without-icon)

## 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 primary
colored, second is secondary, and the last is tertiary
colored.](images/fab/usage-color.webp)




```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](images/fab/usage-sizes.webp)




```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](#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](#fab), branded FABs should always display their logo icon.



![An extended branded fab with a google-colored plus icon and the visible text
Add](images/fab/usage-branded-extended.webp)




```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 medium
sized one and a large one.](images/fab/usage-branded-sizes.webp)




```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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-fab.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-fab-branded.scss)
    

### Branded FAB example



![Image of two branded fabs, one regular, one extended with the visible label
Add with a different theme applied](images/fab/theming-branded.webp)




```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 <code>&lt;md-fab&gt;</code>

#### 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.<br>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 <code>&lt;md-branded-fab&gt;</code>

#### 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.<br>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`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible)
to determine when they are visible.



*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/focus)
    

## 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>
    ```

1.  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>
    ```

1.  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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-focus-ring.scss)
    

### 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 <code>&lt;md-focus-ring&gt;</code>

#### 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `visibility-changed` | `Event` | No | No | Fired whenever `visible` changes. |

---

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

<catalog-component-header>
<catalog-component-header-title slot="title">

# Icon Buttons








**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/icon-button/).**


[Icon buttons](https://m3.material.io/components/icon-buttons) help
people take supplementary actions with a single tap.

</catalog-component-header-title>
<img
    class="hero"
    alt="The top half of a phone application with a back icon button at the top left and three icon buttons on the top right, heart, share, and three dot."
    src="images/iconbutton/hero.webp">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/icon-buttons) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/iconbutton)
    







## Types



")




1.  [Icon Button](#icon-button)
2.  [Filled Icon Button](#filled-icon-button)
3.  [Filled Tonal Icon Button](#filled-tonal-icon-button)
4.  [Outlined Icon Button](#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](icon.md#usage) 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>
```

### Links

Add an
[`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href)
and optionally a
[`target`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/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 bottom
row is
selected](images/iconbutton/usage-toggle.webp "Unselected and Selected Icon Button")




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`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-icon-button.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-filled-icon-button.scss)
    

### 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 <code>&lt;md-icon-button&gt;</code>

#### Properties



| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `softDisabled` | `soft-disabled` | `boolean` | `false` | "Soft-disables" the icon button (disabled but still focusable).<br>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.<br>- 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `input` | `InputEvent` | Yes | Yes | Dispatched when a toggle button toggles |
| `change` | `Event` | Yes | No | Dispatched when a toggle button toggles |



### MdFilledIconButton <code>&lt;md-filled-icon-button&gt;</code>

#### Properties



| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `softDisabled` | `soft-disabled` | `boolean` | `false` | "Soft-disables" the icon button (disabled but still focusable).<br>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.<br>- 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `input` | `InputEvent` | Yes | Yes | Dispatched when a toggle button toggles |
| `change` | `Event` | Yes | No | Dispatched when a toggle button toggles |



### MdFilledTonalIconButton <code>&lt;md-filled-tonal-icon-button&gt;</code>

#### Properties



| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `softDisabled` | `soft-disabled` | `boolean` | `false` | "Soft-disables" the icon button (disabled but still focusable).<br>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.<br>- 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `input` | `InputEvent` | Yes | Yes | Dispatched when a toggle button toggles |
| `change` | `Event` | Yes | No | Dispatched when a toggle button toggles |



### MdOutlinedIconButton <code>&lt;md-outlined-icon-button&gt;</code>

#### Properties



| Property | Attribute | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `softDisabled` | `soft-disabled` | `boolean` | `false` | "Soft-disables" the icon button (disabled but still focusable).<br>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.<br>- 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/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](https://m3.material.io/styles/icons/overview) can be used to
represent common actions. Material Symbols are a set of variable icon fonts
created at seven weights across three different styles.



*   [Design article](https://m3.material.io/styles/icons) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/icon)
    

## 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](https://fonts.google.com/icons) 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`](https://developer.mozilla.org/en-US/docs/Web/CSS/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 `<span>` with an
[`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-icon.scss)
    

### Example



```html
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL@20..48,100..700,0..1" rel="stylesheet">
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL@20..48,100..700,0..1"  rel="stylesheet">
<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Sharp:opsz,wght,FILL@20..48,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`)

<catalog-component-header image-align="start">
<catalog-component-header-title slot="title">

# Lists










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/list/)**




[Lists](https://m3.material.io/components/lists) are continuous,
vertical indexes of text and images

</catalog-component-header-title>

<img class="hero" src="images/list/hero.webp" alt="CImage of a mobile phone screen with a Recipies page and a list recipies in a material list. The first item is Fresh baked breads with an image of someone holding bread on the left and a horizontal three dot menu on the right. Then Tacos with an image of tacos and the same three dot menu">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/lists) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/list)
    







## 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 second
one says Banana in its headline as well as Banana is a yellow fruit as its sub
header. The third list item says Cucumber in its headline and Cucumbers are long
green fruits that are just as long as this multi-line description as its sub
header which is on two lines.](images/list/usage.webp)




```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 has
the Lit logo and the text Lit. The second item has the Polymer logo and the text
Polymer. The third item has the Angular logo and the text
Angular.](images/list/usage-icon.webp)




```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 and
the text Cat. The second is a picture of a kitten with the text Kitty Cat. The
third item is a square image of an older kitten with the text
Cate.](images/list/usage-image.webp)




```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 `type`s 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"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/list_role)
and `tabindex="-1"` for list, and
[`role="listitem"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/listitem_role)
and `tabindex="0"` for list items.

## Theming

List and List Item supports
[Material theming](https://github.com/material-components/material-web/blob/main/docs/theming/README.md)
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`

*   [All List tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list.scss)
    
*   [All List Item tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list-item.scss)
    

### List & List Item Example



![Image of a list and list items of foods with their inventory stock number with
a different theme applied](images/list/theming-list.webp)




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

*   [All List Item tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list-item.scss)
    

### Icon List Item Example



![Image of a list and icon list items of food names with a different theme
applied](images/list/theming-icon.webp)




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

*   [All List Item tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list-item.scss)
    

### 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`

*   [All List Item tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list-item.scss)
    

### 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 <code>&lt;md-list&gt;</code>

#### 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 <code>&lt;md-list-item&gt;</code>

#### 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/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`)

<catalog-component-header>
<catalog-component-header-title slot="title">

# Menus










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/menu/).**




[Menus](https://m3.material.io/components/menus) display a list of
choices on a temporary surface.

</catalog-component-header-title>

<img
    class="hero"
    alt="A phone showing a vertical threedot, pressed, icon button and a menu floating below it with the following visible items: Revert, Settings, and Send Feedback"
    src="images/menu/hero.webp">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/menus) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/menu)
    







## 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-item`s as well as typeahead functionality.
Additionally, `md-menu` interacts with `md-menu-item`s 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 and
the other says set with element ref. There is an opened menu anchored to the
bottom of the right button with the items: Apple, Banana,
Cucumber."](images/menu/usage.webp)




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

### Submenus

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 the
bottom of it with the first item selected that says fruits with A followed by a
right 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 and
another submenu anchored to it on the left. That menu has three items, Fuji,
Granny Smith, and Red Delicious."](images/menu/usage-submenu.webp)




```
/* 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](https://developer.mozilla.org/en-US/docs/Web/API/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](https://developer.mozilla.org/en-US/docs/Glossary/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](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API#browser_compatibility)).
>
> For browsers that do not support the Popover API, `md-menu` will fall back to
> using [fixed-positioned menus](#fixed-positioned-menus).



!["A filled button that says open popover menu. There is an open menu anchored
to the bottom of the button with three items, Apple, Banana, and
Cucumber."](images/menu/usage-popover.webp)




```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](#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 to
the bottom of the button with three items, Apple, Banana, and
Cucumber."](images/menu/usage-fixed.webp)




```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 last child of `<body>`
    -   [Top layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer)
        
-   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 anchored
to the bottom of the button with three items, Apple, Banana, and
Cucumber."](images/menu/usage-document.webp)




```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](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/examples/menu-button-actions/)).

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](../theming/README.md) 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](./list#theming)), so most
the tokens for those components can also be used for Menu.

### Menu Tokens

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`

*   [Menu tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-menu.scss)
    
*   [Menu item tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-menu-item.scss)
    
*   [List tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list.scss)
    
*   [List item tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-list-item.scss)
    

### Example



![A filled button with the text Themed menu. Attached is a 3 item menu with the
items Apple, Banana, and Cucumber. They are both in a green hue and the menu has
a sharp 0px border radius.](images/menu/theming.webp)




```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 <code>&lt;md-menu&gt;</code>

#### 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`.<br>__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`.<br>__Examples for `position = 'fixed'`:__<br>- 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` ancestor<br>When 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`.<br>__NOTE__: Fixed menus will not scroll with the page and will be fixed to the window instead.<br>__Examples for `position = 'document'`:__<br>- 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 `<body>` to render over everything or in a top-layer. - You are reusing a single `md-menu` element that dynamically renders content.<br>__Examples for `position = 'popover'`:__<br>- 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"`.<br>__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.<br>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.<br>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 <block>-<inline> e.g. `'end-start'`.<br>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 <block>-<inline> e.g. `'start-start'`.<br>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.<br>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.<br>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.<br>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.<br>Useful for the case where document or window-positioned menus have their anchors moved while open. |



#### Events



| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/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 <code>&lt;md-menu-item&gt;</code>

#### 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `close-menu` | `CustomEvent<{initiator: SelectOption, reason: Reason, itemPath: SelectOption[]}>` | Yes | Yes | Closes the encapsulating menu on closable interaction. |



### MdSubMenu <code>&lt;md-sub-menu&gt;</code>

#### 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/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`)

<catalog-component-header image-align="end">
<catalog-component-header-title slot="title">

# Progress indicators










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/progress/).**




[Progress indicators](https://m3.material.io/components/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.

</catalog-component-header-title>

<img
    src="images/progress/hero.webp"
    alt="Circular and linear progress indicators showing indetermine and determinate examples"
    title="Progress indicators can be used to show indeterminate or determinate progress.">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/progress-indicators)
    
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/progress)
    

## Types

1.  [Circular progress](#circular-progress)
1.  [Linear progress](#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`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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](../theming/README.md) 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.

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-circular-progress.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-linear-progress.scss)
    

### 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 <code>&lt;md-linear-progress&gt;</code>

#### 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 <code>&lt;md-circular-progress&gt;</code>

#### 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`)

<catalog-component-header image-align="start">
<catalog-component-header-title slot="title">

# Radio button











[Radio buttons](https://m3.material.io/components/radio-button) let
people select one option from a set of options.

</catalog-component-header-title>

<img
    class="hero"
    src="images/radio/hero.webp"
    alt="A list of items with radio buttons and one selected."
    title="Radio buttons">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/radio-button) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/radio)
    







## Usage

Radios behave like
[`<input type="radio">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio)
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`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label)
attribute to radios without labels or radios whose labels need to be more
descriptive.

Place radios inside a
[`role="radiogroup"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role).
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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-radio.scss)
    

### 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 <code>&lt;md-radio&gt;</code>

#### 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.<br>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.<br>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.<br>Disabled and readonly elements will not validate.<br>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.<br>If invalid, this method will dispatch an `invalid` event.<br>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.<br>If invalid, this method will dispatch a cancelable `invalid` event. If not canceled, a the current `validationMessage` will be reported to the user.<br>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.<br>Use this method to customize error messages reported.<br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity |



#### Events



| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/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`)

<catalog-component-header image-align="start">
<catalog-component-header-title slot="title">

# Ripple










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/ripple/)**




Ripples are
[state layers](https://m3.material.io/foundations/interaction/states/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.

</catalog-component-header-title>

<img src="images/ripple/hero.gif" alt="Two containers that display a bounded and unbounded ripple on interaction."
title="A bounded and unbounded ripple.">

</catalog-component-header>

*   [Design article](https://m3.material.io/foundations/interaction/states/state-layers)
    
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/ripple)
    







## 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>
    ```

1.  Attached to a referenced element

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

1.  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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-ripple.scss)
    

### 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 <code>&lt;md-ripple&gt;</code>

#### 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`)

<catalog-component-header image-align="start">
<catalog-component-header-title slot="title">

# Select










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/select/)**




[Select menus](https://m3.material.io/components/menus/overview#b1704de4-94b7-4177-9e96-b677ae767cb4)
display a list of choices on temporary surfaces and display the currently
selected menu item above the menu.

</catalog-component-header-title>

<img class="hero" src="images/select/hero.webp" alt="A textfield containing the text Item 2, with a dropdown menu containing Item 1, Item 2, and Item 3.">

</catalog-component-header>

*   Design article (*coming soon*)
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/select)
    

## 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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select).








```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](https://github.com/material-components/material-web/blob/main/docs/theming/README.md)
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`

*   [Filled Select tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-filled-select.scss)
    

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 tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-outlined-select.scss)
    

### 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 <code>&lt;md-filled-select&gt;</code>

#### 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.<br>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.<br>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.<br>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.<br>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.<br>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.<br>Disabled and readonly elements will not validate.<br>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<boolean>` |  |
| `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.<br>If invalid, this method will dispatch an `invalid` event.<br>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.<br>If invalid, this method will dispatch a cancelable `invalid` event. If not canceled, a the current `validationMessage` will be reported to the user.<br>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.<br>Use this method to customize error messages reported.<br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity |



#### Events



| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `change` | `Event` | Yes | No | The native `change` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) |
| `input` | `InputEvent` | Yes | Yes | The native `input` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) |
| `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 <code>&lt;md-outlined-select&gt;</code>

#### 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.<br>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.<br>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.<br>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.<br>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.<br>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.<br>Disabled and readonly elements will not validate.<br>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<boolean>` |  |
| `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.<br>If invalid, this method will dispatch an `invalid` event.<br>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.<br>If invalid, this method will dispatch a cancelable `invalid` event. If not canceled, a the current `validationMessage` will be reported to the user.<br>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.<br>Use this method to customize error messages reported.<br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity |



#### Events



| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `change` | `Event` | Yes | No | The native `change` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) |
| `input` | `InputEvent` | Yes | Yes | The native `input` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) |
| `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 <code>&lt;md-select-option&gt;</code>

#### 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/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`)

<catalog-component-header image-align="start">
<catalog-component-header-title slot="title">

# Sliders










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/slider/)**




[Sliders](https://m3.material.io/components/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.

</catalog-component-header-title>

<img
    class="hero"
    alt="Sound settings screen with sliders labeled 'Media volume', and 'Call volume'."
    src="images/slider/hero.webp">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/sliders) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/slider)
    







## 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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-slider.scss)
    

### 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 <code>&lt;md-slider&gt;</code>

#### 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `change` | `Event` | Yes | No | The native `change` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) |
| `input` | `InputEvent` | Yes | Yes | The native `input` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) |

---

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

<catalog-component-header>
<catalog-component-header-title slot="title">

# Switch










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/switch/).**




[Switches](https://m3.material.io/components/switch) toggle the state
of an item on or off.

</catalog-component-header-title>

<img
    class="hero"
    src="images/switch/hero.webp"
    alt="Two switches on a settings page for Wi-Fi and Bluetooth. The first is on and the second is off."
    title="Switches on a settings page.">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/switch) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/switch)
    







## 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`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-switch.scss)
    

### 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 <code>&lt;md-switch&gt;</code>

#### 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.<br>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.<br>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.<br>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.<br>Disabled and readonly elements will not validate.<br>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.<br>If invalid, this method will dispatch an `invalid` event.<br>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.<br>If invalid, this method will dispatch a cancelable `invalid` event. If not canceled, a the current `validationMessage` will be reported to the user.<br>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.<br>Use this method to customize error messages reported.<br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity |



#### Events



| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/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`)

<catalog-component-header image-align="start">
<catalog-component-header-title slot="title">

# Tabs










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/tabs/)**




[Tabs](https://m3.material.io/components/tabs) organize groups of
related content that are at the same level of hierarchy.

</catalog-component-header-title>

<img
  class="hero"
  src="images/tabs/hero.webp"
  alt="Media gallery screen with tabs labeled 'Video', 'Photos', and 'Audio'.">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/tabs) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/tabs)
    

## Types

1.  [Primary tabs](#primary-tabs)
1.  [Secondary tabs](#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`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tabpanel_role)
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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-primary-tab.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-secondary-tab.scss)
    

### 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 <code>&lt;md-tabs&gt;</code>

#### 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](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/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 <code>&lt;md-primary-tab&gt;</code>

#### 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 <code>&lt;md-secondary-tab&gt;</code>

#### 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`)

<catalog-component-header image-align="start">
<catalog-component-header-title slot="title">

# Text field










**This documentation is fully rendered on the
[Material Web catalog](https://material-web.dev/components/text-field/)**




[Text fields](https://m3.material.io/components/text-fields) let
users enter text into a UI.

</catalog-component-header-title>

<img class="hero" src="images/textfield/hero.webp" alt="Several text fields in a form"
title="Text fields">

</catalog-component-header>

*   [Design article](https://m3.material.io/components/text-fields) 
*   [API Documentation](#api)
*   [Source code](https://github.com/material-components/material-web/tree/main/textfield)
    

## Types

1.  [Filled text field](#filled-text-field)
1.  [Outlined text field](#outlined-text-field)







## Usage

Text fields behave like
[`<input>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)
elements. They provide a container with labels for user input.



![A filled textfield next to an outlined textfield. Both have a value of Value
prefilled](images/textfield/usage.webp)




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

-   [`type="text"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/text)
    (default)
-   [`type="email"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email)
    
-   [`type="number"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number)
    
-   [`type="password"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password)
    
-   [`type="search"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/search)
    
-   [`type="tel"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/tel)
    
-   [`type="url"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/url)
    
-   [`type="textarea"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)
    



![Two filled textfields next to each other. The first has a label of Username
and the outlined one has a label of Password](images/textfield/usage-type.webp)




```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`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/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 of
Favorite food, the second one a placeholder of email@domain.com and there is a
label that says First name and an empty outlined textfield next to
it](images/textfield/usage-label.webp)




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

<md-outlined-text-field placeholder="email@domain.com">
</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>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/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 Vertical
resize](images/textfield/usage-textarea.webp)




```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 at
the start the label Search Messages, the second a label that says Password and
an eye icon toggle button at the end, and a red, visually errored outlined
textfield with the label Username with an exclamation icon at the end and helper
error text under the field that says Username not
available](images/textfield/usage-icons.webp)




```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 prefix
dollar sign, the number zero as a value and a suffix of decimal zero zero at the
end of the field](images/textfield/usage-prefix.webp)




```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](#validation).



![Two filled fields next to each other. The first has a label that says comments
and 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 under
the field that has an asterisk followed by the word
required](images/textfield/usage-supporting-text.webp)




```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 value
that says Short and the text 5 / 10 under the field at the
end](images/textfield/usage-char-counter.webp)




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

### Validation

Text fields that validate can use
[constraint validation](#constraint-validation) or
[manual validation](#manual-validation).

#### Constraint validation

Text fields may validate using the browser's
[constraint validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation)
API. Each [input type](#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.

-   `validity` is the text field's current
    [`ValidityState`](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState).
-   [`setCustomValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity)
    sets a custom error message.
-   [`checkValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity)
    dispatches an
    [`invalid` event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/invalid_event).
-   [`reportValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity)
    dispatches an
    [`invalid` event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/invalid_event)
    and displays the error in the text field's supporting text.

#### 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](#constraint-validation) when possible for
> more platform features, such as `<form>` validation and listening to `invalid`
> events.

## Accessibility

Add an
[`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/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](https://m3.material.io/components/text-fields/guidelines#83956188-4d8f-4c11-9389-aaba30b10214)
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](https://m3.material.io/components/text-fields/guidelines#83956188-4d8f-4c11-9389-aaba30b10214)
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](../theming/README.md) 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-filled-text-field.scss)
    

### 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`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-outlined-text-field.scss)
    

### 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 <code>&lt;md-filled-text-field&gt;</code>

#### 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.<br>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.<br>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`.<br>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.<br>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.<br>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.<br>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.<br>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.<br>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.<br>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.<br>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.<br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly |
| `multiple` | `multiple` | `boolean` | `false` | Indicates that input accepts multiple email addresses.<br>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.<br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step |
| `type` | `type` | `TextFieldType \| UnsupportedTextFieldType` | `'text'` | The `<input>` type to use, defaults to "text". The type greatly changes how the text field behaves.<br>Text fields support a limited number of `<input>` types:<br>- text - textarea - email - number - password - search - tel - url<br>See 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.<br>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.<br>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.<br>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.<br>Disabled and readonly elements will not validate.<br>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.<br>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.<br>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.<br>For a full list of supported types, see: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/showPicker#browser_compatibility<br>https://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.<br>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.<br>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.<br>If invalid, this method will dispatch an `invalid` event.<br>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.<br>If invalid, this method will dispatch a cancelable `invalid` event. If not canceled, a the current `validationMessage` will be reported to the user.<br>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.<br>Use this method to customize error messages reported.<br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity |



#### Events



| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `select` | `Event` | Yes | No | The native `select` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select_event) |
| `change` | `Event` | Yes | No | The native `change` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) |
| `input` | `InputEvent` | Yes | Yes | The native `input` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) |



### MdOutlinedTextField <code>&lt;md-outlined-text-field&gt;</code>

#### 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.<br>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.<br>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`.<br>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.<br>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.<br>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.<br>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.<br>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.<br>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.<br>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.<br>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.<br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly |
| `multiple` | `multiple` | `boolean` | `false` | Indicates that input accepts multiple email addresses.<br>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.<br>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#step |
| `type` | `type` | `TextFieldType \| UnsupportedTextFieldType` | `'text'` | The `<input>` type to use, defaults to "text". The type greatly changes how the text field behaves.<br>Text fields support a limited number of `<input>` types:<br>- text - textarea - email - number - password - search - tel - url<br>See 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.<br>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.<br>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.<br>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.<br>Disabled and readonly elements will not validate.<br>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.<br>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.<br>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.<br>For a full list of supported types, see: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/showPicker#browser_compatibility<br>https://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.<br>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.<br>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.<br>If invalid, this method will dispatch an `invalid` event.<br>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.<br>If invalid, this method will dispatch a cancelable `invalid` event. If not canceled, a the current `validationMessage` will be reported to the user.<br>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.<br>Use this method to customize error messages reported.<br>https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity |



#### Events



| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
| --- | --- | --- | --- | --- |
| `select` | `Event` | Yes | No | The native `select` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select_event) |
| `change` | `Event` | Yes | No | The native `change` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) |
| `input` | `InputEvent` | Yes | Yes | The native `input` event on [`<input>`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) |

---

### 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](https://m3.material.io/styles/color/overview) creates meaning
and communicates hierarchy, state, and brand.

## Color scheme



A
[color scheme](https://m3.material.io/styles/color/the-color-system/color-roles#55d2b7d2-0202-4616-887e-f575a7946aac)
is the group of
[key color tones](https://m3.material.io/styles/color/the-color-system/key-colors-tones#5fdf196d-1e21-4d03-ae63-e802d61ad5ee)
assigned to specific roles that get mapped to components.





> Tip: use the
> [Material theme builder Figma plugin](https://www.figma.com/community/plugin/1034969338659738588/Material-Theme-Builder)
> to generate a color scheme.
>
> Alternatively, use the
> [`material-color-utilities` library](https://www.npmjs.com/package/@material/material-color-utilities)
> to generate color schemes at runtime.

### Tokens

A color scheme can be set using
[CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*).
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`
&nbsp;    | `--md-sys-color-primary-container`
Secondary | `--md-sys-color-secondary`
&nbsp;    | `--md-sys-color-secondary-container`
Tertiary  | `--md-sys-color-tertiary`
&nbsp;    | `--md-sys-color-tertiary-container`
Error     | `--md-sys-color-error`
&nbsp;    | `--md-sys-color-error-container`
Neutral   | `--md-sys-color-background`
&nbsp;    | `--md-sys-color-surface`
&nbsp;    | `--md-sys-color-surface-bright` *
&nbsp;    | `--md-sys-color-surface-dim` *
&nbsp;    | `--md-sys-color-surface-container` *
&nbsp;    | `--md-sys-color-surface-container-lowest` *
&nbsp;    | `--md-sys-color-surface-container-low` *
&nbsp;    | `--md-sys-color-surface-container-high` *
&nbsp;    | `--md-sys-color-surface-container-highest` *
&nbsp;    | `--md-sys-color-outline`
&nbsp;    | `--md-sys-color-outline-variant`

*\* all surface tokens use `--md-sys-color-on-surface` or
`--md-sys-color-on-surface-variant` for their content.*

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-sys-color.scss)
    

```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](https://m3.material.io/styles/shape) can direct attention,
communicate state, and express brand.

## Shape



Corners use a
[range of shape scales](https://m3.material.io/styles/shape/shape-scale-tokens#b85fe884-325c-45e6-b7fb-e753c6e03c82)
for their roundness, from straight to fully round.

> Note: "cut" corners are not supported.

### Tokens

Shape corners can be set using
[CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*).
Tokens follow the naming convention `--md-sys-shape-<token>`.

Shape  | Token
------ | -----------------------------------
Corner | `--md-sys-shape-corner-none`
&nbsp; | `--md-sys-shape-corner-extra-small`
&nbsp; | `--md-sys-shape-corner-small`
&nbsp; | `--md-sys-shape-corner-medium`
&nbsp; | `--md-sys-shape-corner-large`
&nbsp; | `--md-sys-shape-corner-extra-large`
&nbsp; | `--md-sys-shape-corner-full`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-sys-shape.scss)
    

```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](https://m3.material.io/styles/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](https://m3.material.io/styles/typography/fonts) 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](https://fonts.google.com/share?selection.family=Roboto:wght@400;500;700).

### Tokens

Typefaces can be set using
[CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*).
Tokens follow the naming convention `--md-ref-typeface-<token>`.

Typeface | Token
-------- | -------------------------
Brand    | `--md-ref-typeface-brand`
Plain    | `--md-ref-typeface-plain`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-ref-typeface.scss)
    

```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](https://m3.material.io/styles/typography/type-scale-tokens)
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](https://m3.material.io/styles/typography/applying-type)
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](https://developer.mozilla.org/en-US/docs/Web/CSS/--*).
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>-<property>`.

Typescale | Tokens
--------- | ------------------------------------------------
Display   | `--md-sys-typescale-display-medium-font`
&nbsp;    | `--md-sys-typescale-display-medium-size`
&nbsp;    | `--md-sys-typescale-display-medium-line-height`
&nbsp;    | `--md-sys-typescale-display-medium-weight`
Headline  | `--md-sys-typescale-headline-medium-font`
&nbsp;    | `--md-sys-typescale-headline-medium-size`
&nbsp;    | `--md-sys-typescale-headline-medium-line-height`
&nbsp;    | `--md-sys-typescale-headline-medium-weight`
Title     | `--md-sys-typescale-title-medium-font`
&nbsp;    | `--md-sys-typescale-title-medium-size`
&nbsp;    | `--md-sys-typescale-title-medium-line-height`
&nbsp;    | `--md-sys-typescale-title-medium-weight`
Body      | `--md-sys-typescale-body-medium-font`
&nbsp;    | `--md-sys-typescale-body-medium-size`
&nbsp;    | `--md-sys-typescale-body-medium-line-height`
&nbsp;    | `--md-sys-typescale-body-medium-weight`
Label     | `--md-sys-typescale-label-medium-font`
&nbsp;    | `--md-sys-typescale-label-medium-size`
&nbsp;    | `--md-sys-typescale-label-medium-line-height`
&nbsp;    | `--md-sys-typescale-label-medium-weight`

*   [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-sys-typescale.scss)
    

```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 ---
- Files Extracted: 37
- Estimated Token Budget: ~73462 tokens
- Canonical Reference: https://codewiki.google/github.com/material-components/material-web