@material/mwc-select
@material/mwc-select
npm i @material/mwc-select
@material/mwc-select

@material/mwc-select

Material Design Web Components

by material-components

0.27.0 (see all)License:Apache-2.0TypeScript:Not Found
npm i @material/mwc-select
Readme

<mwc-select> Published on npm

IMPORTANT: The Material Web Components are a work in progress and subject to major changes until 1.0 release.

Selects display a list of choices on temporary surfaces.

Material Design Guidelines: exposed dropdown menus

Demo

Installation

npm install @material/mwc-select

NOTE: The Material Web Components are distributed as ES2017 JavaScript Modules, and use the Custom Elements API. They are compatible with all modern browsers including Chrome, Firefox, Safari, Edge, and IE11, but an additional tooling step is required to resolve bare module specifiers, as well as transpilation and polyfills for IE11. See here for detailed instructions.

Example usage

Basic (filled)

Note, mwc-select internally uses mwc-list, so its main slot has the same interface as the main slot of a mwc-list.


<mwc-select label="filled">
  <mwc-list-item></mwc-list-item>
  <mwc-list-item value="0">Item 0</mwc-list-item>
  <mwc-list-item value="1">Item 1</mwc-list-item>
  <mwc-list-item value="2">Item 2</mwc-list-item>
  <mwc-list-item value="3">Item 3</mwc-list-item>
</mwc-select>

<script type="module">
  import '@material/mwc-select/mwc-select.js';
  import '@material/mwc-list/mwc-list-item.js';
</script>

Outlined


<mwc-select outlined label="outlined">
  <mwc-list-item></mwc-list-item>
  <mwc-list-item value="0">Item 0</mwc-list-item>
  <mwc-list-item value="1">Item 1</mwc-list-item>
  <mwc-list-item value="2">Item 2</mwc-list-item>
  <mwc-list-item value="3">Item 3</mwc-list-item>
</mwc-select>

Preselected


<mwc-select label="preselected">
  <mwc-list-item></mwc-list-item>
  <mwc-list-item selected value="0">Item 0</mwc-list-item>
  <mwc-list-item value="1">Item 1</mwc-list-item>
  <mwc-list-item value="2">Item 2</mwc-list-item>
  <mwc-list-item value="3">Item 3</mwc-list-item>
</mwc-select>

Icon

Icon is a material-icons font name. Additionally, all options must have graphic="icon" defined to enable proper spacing.


<mwc-select label="has icon" icon="event">
  <mwc-list-item graphic="icon" value="1">Option 1</mwc-list-item>
  <mwc-list-item graphic="icon" value="2">Option 2</mwc-list-item>
  <mwc-list-item graphic="icon" value="3">Option 3</mwc-list-item>
</mwc-select>

Required (error, validation message)


<mwc-select
    required
    validationMessage="This Field is Required"
    label="required (error)">
  <mwc-list-item selected></mwc-list-item>
  <mwc-list-item value="0">Item 0</mwc-list-item>
  <mwc-list-item value="1">Item 1</mwc-list-item>
  <mwc-list-item value="2">Item 2</mwc-list-item>
  <mwc-list-item value="3">Item 3</mwc-list-item>
</mwc-select>
<mwc-select
    required
    validationMessage="This Field is Required"
    outlined
    label="required (error)">
  <mwc-list-item selected></mwc-list-item>
  <mwc-list-item value="0">Item 0</mwc-list-item>
  <mwc-list-item value="1">Item 1</mwc-list-item>
  <mwc-list-item value="2">Item 2</mwc-list-item>
  <mwc-list-item value="3">Item 3</mwc-list-item>
</mwc-select>

Helper Text


focused:

<mwc-select
    label="has helper text"
    helper="Helper Text">
  <mwc-list-item></mwc-list-item>
  <mwc-list-item selected value="0">Item 0</mwc-list-item>
  <mwc-list-item value="1">Item 1</mwc-list-item>
  <mwc-list-item value="2">Item 2</mwc-list-item>
  <mwc-list-item value="3">Item 3</mwc-list-item>
</mwc-select>

Styled


<style>
  mwc-select {
    --mdc-theme-primary: blue;
    --mdc-select-fill-color: aliceblue;
    --mdc-select-label-ink-color: rgba(0, 0, 0, 0.75);
    --mdc-select-dropdown-icon-color: blue;

    --mdc-select-idle-line-color: rgba(0, 0, 255, 0.42);
    --mdc-select-hover-line-color: rgba(0, 0, 255, 0.87);

    --mdc-select-outlined-idle-border-color: rgba(0, 0, 255, 0.42);
    --mdc-select-outlined-hover-border-color: rgba(0, 0, 255, 0.87);

    /* inherits the styles of mwc-menu internally */
    --mdc-menu-item-height: 30px;
    --mdc-theme-surface: aliceblue;

    /* inherits the styles of mwc-list internally */
    --mdc-list-vertical-padding: 0px;
    --mdc-list-side-padding: 30px;
  }
</style>
<mwc-select helper="Helper Text" label="styled">
  <mwc-list-item></mwc-list-item>
  <mwc-list-item selected value="0">Item 0</mwc-list-item>
  <mwc-list-item value="1">Item 1</mwc-list-item>
  <mwc-list-item value="2">Item 2</mwc-list-item>
  <mwc-list-item value="3">Item 3</mwc-list-item>
</mwc-select>
<mwc-select outlined helper="Helper Text" label="styled">
  <mwc-list-item></mwc-list-item>
  <mwc-list-item selected value="0">Item 0</mwc-list-item>
  <mwc-list-item value="1">Item 1</mwc-list-item>
  <mwc-list-item value="2">Item 2</mwc-list-item>
  <mwc-list-item value="3">Item 3</mwc-list-item>
</mwc-select>

API

Slots

NameDescription
defaultContent to display in the selects internal <mwc-menu> element.

mwc-select internally uses mwc-list, so the default slot has the same interface as the default slot of mwc-list.

Properties/Attributes

NameTypeDefaultDescription
valuestring""The select control's value determined by the value property of the currently selected list item. Setting value will attempt to select a list-item with the same value. If one does not match, it will set itself to "" and the index to -1. Setting value before the list item is attached will not select the item.
labelstring""Sets floating label value. NOTE: The label will not float if the selected item has a falsey value property.
naturalMenuWidthstringfalseSets the dropdown menu's width to auto.
fixedMenuPositionbooleanfalseSets the dropdown menu's position to fixed. This is useful when the select is inside of a stacking context e.g. inside of an mwc-dialog. Note, that --mdc-menu-min-width or --mdc-menu-max-width may have to be set to resize the menu to the width anchor.
iconstring""Leading icon to display in select. See mwc-icon. Note: for proper list spacing, each list item must have graphic="icon" or graphic="avatar" to be set.
disabledbooleanfalseWhether or not the select should be disabled.
outlinedbooleanfalseWhether or not to show the material outlined variant.
helperstring""Helper text to display below the select. Always displays by default.
requiredbooleanfalseDisplays error state if value is empty and select is blurred.
validationMessagestring""Message to show in the error color when the select is invalid. (Helper text will not be visible)
selectedListItemBase|nullnullSelected list item element.
itemsListItemBase[][]List of selectable items.
indexnumber-1Index of selected list item.
validityValidityState (readonly)DefaultValidity*The ValidityState of the select.
validityTransformValidityTransform**|nullnullCallback called before each validation check. See the mwc-textfield's validation section for more details.
validateOnInitialRenderbooleanfalseRuns validation check on initial render.

* DefaultValidity is: ts { badInput: false, customError: false, patternMismatch: false, rangeOverflow: false, rangeUnderflow: false, stepMismatch: false, tooLong: false, tooShort: false, typeMismatch: false, valid: true, valueMissing: false, }

** See mwc-textfield's properties section for more info.

Methods

NameDescription
checkValidity() => booleanReturns true if the select passes validity checks. Returns false and fires an invalid event on the select otherwise.
NOTE: When accessing any property or function that checks validity at select initial boot up, you may have to await <mwc-select>.updateComplete.
reportValidity() => booleanRuns checkValidity() method, and if it returns false, then it reports to the user that the input is invalid.
setCustomValidity(message:string) => voidSets a custom validity message (also overwrites validationMessage). If this message is not the empty string, then the element is suffering from a custom validity error and does not validate.
select(index: number) => voidSelects the element at the given index.
layout(updateItems = true) => Promise<void>Resets tabindex on all items and will update items model if provided true. It may be required to call layout if selectability of an element is dynamically changed. e.g. [mwc-list-item] attribute is removed from a list item or noninteractive is dynamically set on a list item. Also re-calculates layout. If a select is styled with display:none before it is first rendered, and it has a label that is floating, then you must call layout() the first time you remove display:none, or else the notch surrounding the label will not render correctly.
layoutOptions() => Promise<void>Synchronizes the list of options with the model of the component and updates the selected text. Call this if the selected item is dynamically updated in value or text.

Events

Event NameTargetDetailDescription
openedmwc-select-surfacenoneFired menu opens.
closedmwc-select-surfacenoneFired menu closes.
selectedmwc-listSelectedDetail*Fired when a selection has been made. Property index is the selected index (will be of type number)

* See mwc-list's Events section for more details.

CSS Custom Properties

mwc-select internally uses both mwc-menu and mwc-list, so all custom properties from mwc-menu and mwc-list propagate through mwc-select.

NameDefaultDescription
--mdc-select-error-color--mdc-theme-errorApplies where --mdc-theme-error applies.
--mdc-select-idle-line-color rgba(0, 0, 0, 0.42)Color of the filled select's bottom line when idle.
--mdc-select-hover-line-color rgba(0, 0, 0, 0.87)Color of the filled select's bottom line when hovering.
--mdc-select-outlined-idle-border-color rgba(0, 0, 0, 0.38)Color of the outlined select's outline when idle.
--mdc-select-outlined-hover-border-color rgba(0, 0, 0, 0.87)Color of the outlined select's outline when hovering.
--mdc-select-outlined-disabled-border-color rgba(0, 0, 0, 0.16)Color of the outlined select's outline when disabled.
--mdc-select-fill-color rgb(245, 245, 245)Color of the select's background fill (non-outlined).
--mdc-select-disabled-fill-color rgb(250, 250, 250)Color of the select's background fill (non-outlined) when disabled.
--mdc-select-ink-color rgba(0, 0, 0, 0.87)Color of the selected text in default and error states.
--mdc-select-label-ink-color rgba(0, 0, 0, 0.6)Color of the non-focused floating label, helper text, and placeholder.
--mdc-select-focused-label-color--mdc-theme-primaryColor of the focused floating label, helper text, and placeholder.
--mdc-select-disabled-ink-color rgba(0, 0, 0, 0.37)Color of the input text, the floating label, helper text, and placeholder of a disabled select.
--mdc-select-dropdown-icon-colorrgba(0, 0, 0, 0.54)Color of the dropdown icon when select is not activated.
--mdc-select-focused-dropdown-icon-color--mdc-theme-primaryColor of the dropdown icon when select is activated.
--mdc-select-disabled-dropdown-icon-color rgba(0, 0, 0, 0.38)Opacity of the dropdown icon when disabled.
--mdc-select-error-dropdown-icon-color--mdc-select-error-colorColor of the dropdown icon when select is invalid.

mwc-select internally uses mwc-list, see the styling documentation for further details.

Global Custom Properties

This component exposes the following global theming custom properties.

NameDescription
--mdc-theme-primaryColor when active of the underline ripple, the outline, the caret, the dropdown-icon, and the focused and activatd list items.
--mdc-theme-errorColor when errored of the underline ripple, the outline, the caret, the dropdown-icon, and the focused and activatd list items.
--mdc-typography-subtitle1-<PROPERTY>Styles the typography of the selected text.

Additional references

Downloads/wk

7.7K

GitHub Stars

2.6K

LAST COMMIT

NaNyrs ago

MAINTAINERS

15

CONTRIBUTORS

0

OPEN ISSUES

205

OPEN PRs

29
VersionTagPublished
0.27.0
latest
4mos ago
0.26.0-canary.0af8ade5.0
canary
10mos ago
No alternatives found
No tutorials found
Add a tutorial
No dependencies found

Rate & Review

100
No reviews found
Be the first to rate