toc

Select

Select menus let people choose one option from a list that opens on a temporary surface.

Apple

Apricot

Banana

<md-gb-select label="Fruit">
  <md-gb-select-option value="apple">Apple</md-gb-select-option>
  <md-gb-select-option value="apricot">Apricot</md-gb-select-option>
  <md-gb-select-option value="banana">Banana</md-gb-select-option>
</md-gb-select>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-select.json (setup)

Usage guidelines

Link to “Usage guidelines”

Fixed list of choices. Use a select to choose one value from a short, fixed list, like the native <select>. For a longer list that people can search, use the autocomplete.
Pick the variant by emphasis. Filled selects stand out more; outlined selects are lighter on dense forms.
Say what is wrong. Pair an error with text that explains how to fix it.

Anatomy

Link to “Anatomy”

A select holds options and a field that shows the chosen one. Options can have icons and extra text.

local_shipping

schedule

3 to 5 days Free check Standard

bolt

Next day $8 Express

<md-gb-select label="Delivery">
  <md-gb-icon slot="leading-icon">local_shipping</md-gb-icon>
  <md-gb-select-option value="standard">
    <md-gb-icon slot="leading">schedule</md-gb-icon>
    <span slot="supporting-text">3 to 5 days</span>
    <span slot="trailing-text">Free</span>
    <md-gb-icon slot="trailing">check</md-gb-icon>
    Standard
  </md-gb-select-option>
  <md-gb-select-option value="express">
    <md-gb-icon slot="leading">bolt</md-gb-icon>
    <span slot="supporting-text">Next day</span>
    <span slot="trailing-text">$8</span>
    Express
  </md-gb-select-option>
</md-gb-select>

Examples

Link to “Examples”

Variants

Link to “Variants”

Selects are filled by default. Set variant="outlined" for an outlined field.

Apple

Apricot

<md-gb-select label="Fruit" variant="outlined">
  <md-gb-select-option value="apple">Apple</md-gb-select-option>
  <md-gb-select-option value="apricot">Apricot</md-gb-select-option>
</md-gb-select>

Selected option

Link to “Selected option”

Add selected to an option, or set value on the select, to choose one at the start.

Home

Mobile

Work

<md-gb-select label="Phone type" value="mobile">
  <md-gb-select-option value="home">Home</md-gb-select-option>
  <md-gb-select-option value="mobile">Mobile</md-gb-select-option>
  <md-gb-select-option value="work">Work</md-gb-select-option>
</md-gb-select>

Option content

Link to “Option content”

Options take a leading icon, supporting-text, trailing-text and a trailing icon. Disabled options can't be chosen.

Free 1 project $0

Pro Unlimited projects $8

Team Coming soon

<md-gb-select label="Plan" variant="outlined">
  <md-gb-select-option value="free">
    Free
    <span slot="supporting-text">1 project</span>
    <span slot="trailing-text">$0</span>
  </md-gb-select-option>
  <md-gb-select-option value="pro">
    Pro
    <span slot="supporting-text">Unlimited projects</span>
    <span slot="trailing-text">$8</span>
  </md-gb-select-option>
  <md-gb-select-option value="team" disabled>
    Team
    <span slot="supporting-text">Coming soon</span>
  </md-gb-select-option>
</md-gb-select>

Leading icon

Link to “Leading icon”

An icon in the leading-icon slot sits before the chosen text.

phone

business_center Business

smartphone Mobile

<md-gb-select label="Phone type" value="mobile">
  <md-gb-icon slot="leading-icon">phone</md-gb-icon>
  <md-gb-select-option value="business">
    <md-gb-icon slot="leading">business_center</md-gb-icon>
    Business
  </md-gb-select-option>
  <md-gb-select-option value="mobile">
    <md-gb-icon slot="leading">smartphone</md-gb-icon>
    Mobile
  </md-gb-select-option>
</md-gb-select>

Error and supporting text

Link to “Error and supporting text”

Use supporting-text for a hint. When error is set, error-text replaces it. Add required to mark the field as mandatory.

Canada

Mexico

<md-gb-select label="Country" required error error-text="Choose a country">
  <md-gb-select-option value="ca">Canada</md-gb-select-option>
  <md-gb-select-option value="mx">Mexico</md-gb-select-option>
</md-gb-select>

Autocomplete

Link to “Autocomplete”

md-gb-autocomplete is a text field with the same options, filtered as people type. Set filter to change how options match.

Alabama

Alaska

Arizona

<md-gb-autocomplete label="State">
  <md-gb-select-option>Alabama</md-gb-select-option>
  <md-gb-select-option>Alaska</md-gb-select-option>
  <md-gb-select-option>Arizona</md-gb-select-option>
</md-gb-autocomplete>

In a form

Link to “In a form”

A select takes part in a form through its name and value, and required is checked on submit.

<form>
  <md-gb-select name="size" label="Size" required>
    <md-gb-select-option value="s">Small</md-gb-select-option>
    <md-gb-select-option value="m">Medium</md-gb-select-option>
    <md-gb-select-option value="l">Large</md-gb-select-option>
  </md-gb-select>
  <md-gb-button type="submit">Order</md-gb-button>
</form>

Accessibility

Link to “Accessibility”

The field is a combobox and the menu a listbox. The label names the field; add an aria-label when the label is elsewhere.
Enter, Space, or the arrow keys open the menu, the arrow keys move between options, and Escape closes it. Typing a few letters jumps to a matching option.

Newest

Oldest

<md-gb-select aria-label="Sort by" value="new">
  <md-gb-select-option value="new">Newest</md-gb-select-option>
  <md-gb-select-option value="old">Oldest</md-gb-select-option>
</md-gb-select>

Compatibility

Link to “Compatibility”

Material Design 30 uncovered97% tokens

124 of 325 buildable spec units are tested, 35 are excluded with a written reason and 0 are uncovered (the target is 0). 248 of 256 token declarations match the spec (97%), 2 differ on purpose or are being fixed, and 6 have no spec token.

menus on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

@starting-style (opens in a new tab) Newly available degrades safely where it is missing
Anchor positioning (opens in a new tab) Limited availability used inside an @supports guard
Cursor styles (opens in a new tab) Limited availability degrades safely where it is missing
overscroll-behavior (opens in a new tab) Limited availability degrades safely where it is missing
scrollbar-color (opens in a new tab) Newly available degrades safely where it is missing
scrollbar-gutter (opens in a new tab) Newly available degrades safely where it is missing
scrollbar-width (opens in a new tab) Newly available degrades safely where it is missing
user-select (opens in a new tab) Limited availability used inside an @supports guard

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passComboboxListbox

Roles the component renders: combobox (opens in a new tab), listbox (opens in a new tab), option (opens in a new tab), textbox (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Combobox (opens in a new tab), Listbox (opens in a new tab).

5 rendered states run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse98 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

Eliminate render-blocking resources
Minify JavaScript
Reduce unused CSS
Enable text compression
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-autocomplete>

Link to “<md-gb-autocomplete>”

A Material Design component.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`error` Whether the field is in a visually invalid state. Overrides the error state set by `reportValidity()`.	`error`	`boolean`	`false`
`errorText` The message that replaces the supporting text while `error` is true. Overrides the message shown by `reportValidity()`.	`error-text`	`string`	`''`
`filter` How options are filtered by the typed text: `contains` (default), `starts-with`, or `none` (the page updates the options itself, e.g. from a server, on `input`).	`filter`	`AutocompleteFilter`	`'contains'`
`hasLeadingIcon` Whether a leading icon is slotted. Set it for SSR.	`has-leading-icon`	`boolean`	`false`
`label` The floating label; also the field's accessible name.	`label`	`string`	`''`
`noAsterisk` Hides the asterisk added to the label of a required field.	`no-asterisk`	`boolean`	`false`
`open` Whether the menu is open.	`open`	`boolean`	`false`
`placeholder` Hint text shown in the input while it is empty and the label floats.	`placeholder`	`string`	`''`
`required` Whether a value is required. Adds an asterisk to the label.	`required`	`boolean`	`false`
`supportingText` Additional information shown below the field.	`supporting-text`	`string`	`''`
`value` The text in the field.	`value`	`string`	`''`
`variant` The variant: `filled` (default) or `outlined`.	`variant`	`TextFieldVariant`	`'filled'`

Slots

Link to “Slots”

Slot	Description
default	The `md-gb-select-option` suggestions.
`leading-icon`	An icon before the input.
`trailing-icon`	Replaces the dropdown arrow icon.

Events

Link to “Events”

Event	Description
`change` Event	The text was committed (picked option or native change).
`closed` Event	The menu closed.
`closing` Event	The menu is about to close.
`input` InputEvent	The text changed by typing or picking an option.
`invalid` Event	Fired when `checkValidity()` or `reportValidity()` finds the field invalid.
`opened` Event	The menu opened.
`opening` Event	The menu is about to open.

Methods

Link to “Methods”

Method	Description
`blur` () => void	MDN Reference
`focus` (options?: FocusOptions) => void	MDN Reference
`reset` () => void	Restores the `value` attribute and clears native errors.
`select` () => void	Selects all the text.
`setCustomValidity` (error: string) => void	Sets the element's constraint validation error message. When set to a non-empty string, `validity.customError` will be true and `validationMessage` will display the provided error. Use this method to customize error messages reported. https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity
`showPicker` () => void	Opens the menu.

CSS parts

Link to “CSS parts”

Part	Description
`::part(arrow)`	The dropdown arrow.
`::part(container)`	The field's container.
`::part(input)`	The native `<input>`.
`::part(label)`	The floating label.
`::part(menu)`	The `listbox` menu.
`::part(supporting-text)`	The supporting or error text.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--caret-color`	Input caret color.
`--container-color`	Field container color.
`--input-text-color`	Input text color.
`--label-text-color`	Label color.
`--menu-min-width`	Minimum menu width.
`--trailing-icon-expanded-rotation`	Dropdown arrow rotation while open.

<md-gb-select>

Link to “<md-gb-select>”

A Material Design component.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`displayText` The text shown in the field. Defaults to the selected option's `displayText`; set it for SSR.	`display-text`	`string`
`error` Whether the field is in a visually invalid state. Overrides the error state set by `reportValidity()`.	`error`	`boolean`	`false`
`errorText` The message that replaces the supporting text while `error` is true. Overrides the message shown by `reportValidity()`.	`error-text`	`string`	`''`
`hasLeadingIcon` Whether a leading icon is slotted. Set it for SSR.	`has-leading-icon`	`boolean`	`false`
`label` The floating label; also the field's accessible name.	`label`	`string`	`''`
`noAsterisk` Hides the asterisk added to the label of a required field.	`no-asterisk`	`boolean`	`false`
`open` Whether the menu is open.	`open`	`boolean`	`false`
`required` Whether a value is required. Adds an asterisk to the label.	`required`	`boolean`	`false`
`selectedIndex` The index of the selected option, or -1.	`selected-index`	`number`
`supportingText` Additional information shown below the field.	`supporting-text`	`string`	`''`
`typeaheadDelay` The longest time between typeahead keystrokes, in milliseconds.	`typeahead-delay`	`number`	`DEFAULT_TYPEAHEAD_DELAY`
`value` The value of the selected option, or `''`. Setting it selects the first option with that value (or none).	`value`	`string`
`variant` The variant: `filled` (default) or `outlined`.	`variant`	`TextFieldVariant`	`'filled'`

Slots

Link to “Slots”

Slot	Description
default	The `md-gb-select-option`s (and dividers).
`leading-icon`	An icon before the selected text.
`trailing-icon`	Replaces the dropdown arrow icon.

Events

Link to “Events”

Event	Description
`change` Event	The person selected a different option.
`closed` Event	The menu closed.
`closing` Event	The menu is about to close.
`input` InputEvent	The person selected a different option.
`invalid` Event	Fired when `checkValidity()` or `reportValidity()` finds the select invalid.
`opened` Event	The menu opened.
`opening` Event	The menu is about to open.

Methods

Link to “Methods”

Method	Description
`blur` () => void	MDN Reference
`focus` (options?: FocusOptions) => void	MDN Reference
`reset` () => void	Restores the default selection (`selected` attributes).
`select` (value: string) => void	Selects the first option with the given value.
`selectIndex` (index: number) => void	Selects the option at the given index.
`setCustomValidity` (error: string) => void	Sets the element's constraint validation error message. When set to a non-empty string, `validity.customError` will be true and `validationMessage` will display the provided error. Use this method to customize error messages reported. https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity
`showPicker` () => void	Opens the menu.

CSS parts

Link to “CSS parts”

Part	Description
`::part(arrow)`	The dropdown arrow.
`::part(container)`	The field's container.
`::part(field)`	The `combobox` showing the selected text.
`::part(label)`	The floating label.
`::part(menu)`	The `listbox` menu.
`::part(supporting-text)`	The supporting or error text.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--active-indicator-color`	Filled active indicator color.
`--active-indicator-height`	Filled active indicator thickness.
`--container-color`	Field container color.
`--container-shape`	Field container corner radius.
`--input-text`	Selected text typography.
`--input-text-axes`	Selected text font variation settings.
`--input-text-color`	Selected text color.
`--input-text-tracking`	Selected text letter spacing.
`--label-text`	Label typography.
`--label-text-axes`	Label font variation settings.
`--label-text-color`	Label color.
`--label-text-populated-line-height`	Floated label line height.
`--label-text-populated-size`	Floated label font size.
`--label-text-tracking`	Label letter spacing.
`--leading-icon-color`	Leading icon color.
`--leading-icon-size`	Leading icon size.
`--menu-closed-scale`	Scale the menu opens from.
`--menu-min-width`	Minimum menu width.
`--menu-window-margin`	Space kept between the menu and the window edge.
`--outline-color`	Outlined container outline color.
`--outline-width`	Outlined container outline width.
`--supporting-text`	Supporting text typography.
`--supporting-text-axes`	Supporting text font variation settings.
`--supporting-text-color`	Supporting text color.
`--supporting-text-tracking`	Supporting text letter spacing.
`--trailing-icon-color`	Dropdown arrow color.
`--trailing-icon-expanded-rotation`	Dropdown arrow rotation while open.
`--trailing-icon-size`	Dropdown arrow size.

<md-gb-select-option>

Link to “<md-gb-select-option>”

A Material Design component.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`disabled` Whether the option cannot be selected. It can still become active.	`disabled`	`boolean`	`false`
`displayText` The text shown in the field when the option is selected. Defaults to the option's label text.	`display-text`	`string`
`selected` Whether the option is selected. The `selected` attribute is the default selection restored on form reset.	`selected`	`boolean`
`typeaheadText` The text matched by typeahead and filtering. Defaults to `displayText`.	`typeahead-text`	`string`
`value` The form value. Defaults to `displayText`, like a native `<option>`.	`value`	`string`

Slots

Link to “Slots”

Slot	Description
default	The option's label.
`leading`	An icon before the label. Without one, a selected option shows a checkmark.
`supporting-text`	Supporting text below the label.
`trailing`	An icon after the label.
`trailing-text`	Metadata after the label, such as a keyboard shortcut.

CSS parts

Link to “CSS parts”

Part	Description
`::part(menu-item)`	The option's root element.

Select

Usage guidelines

Anatomy

Examples

Variants

Selected option

Option content

Leading icon

Error and supporting text

Autocomplete

In a form

Accessibility

Compatibility

API reference

<md-gb-autocomplete>

Properties

Slots

Events

Methods

CSS parts

CSS custom properties

<md-gb-select>

Properties

Slots

Events

Methods

CSS parts

CSS custom properties

<md-gb-select-option>

Properties

Slots

CSS parts

Download & copy

Download

Copy

Customize theme