Default Gray Amethyst

Select

<mo-select> | MOSelect
Since 1.0 stable

Selects allow you to choose items from a menu of predefined options.

Option 1 Option 2 Option 3 
<mo-select>
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

import { MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect>
    <MOOption value="option-1">Option 1</MOOption>
    <MOOption value="option-2">Option 2</MOOption>
    <MOOption value="option-3">Option 3</MOOption>
  </MOSelect>
);

Examples

Placeholders

Use the placeholder attribute to add a placeholder.

Option 1 Option 2 Option 3 
<mo-select placeholder="Select one">
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

import { MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect placeholder="Select one">
    <MOOption value="option-1">Option 1</MOOption>
    <MOOption value="option-2">Option 2</MOOption>
    <MOOption value="option-3">Option 3</MOOption>
  </MOSelect>
);

Required

Use the required attribute to add an asterisk that notifies the user the field cannot be empty.

Option 1 Option 2 Option 3 
<mo-select label="Choose option" required placeholder="Select one">
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

import { MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect label="Choose option" required placeholder="Select one">
    <MOOption value="option-1">Option 1</MOOption>
    <MOOption value="option-2">Option 2</MOOption>
    <MOOption value="option-3">Option 3</MOOption>
  </MOSelect>
);

Clearable

Use the clearable attribute to make the control clearable.

Option 1 Option 2 Option 3 
<mo-select placeholder="Clearable" clearable>
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

import { MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect placeholder="Clearable" clearable>
    <MOOption value="option-1">Option 1</MOOption>
    <MOOption value="option-2">Option 2</MOOption>
    <MOOption value="option-3">Option 3</MOOption>
  </MOSelect>
);

Disabled

Use the disabled attribute to disable a select.

Option 1 Option 2 Option 3 
<mo-select placeholder="Disabled" disabled value="option-1">
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

import { MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect placeholder="Disabled" disabled value="option-1">
    <MOOption value="option-1">Option 1</MOOption>
    <MOOption value="option-2">Option 2</MOOption>
    <MOOption value="option-3">Option 3</MOOption>
  </MOSelect>
);

Setting the selection

Use the value attribute to set the current selection. When users interact with the control, its value will update to reflect the newly selected menu item’s value. Note that the value must be an array when using the multiple option.

Option 1 Option 2 Option 3 
<mo-select value="option-2">
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

import { MODivider, MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect value="option-2">
    <MOOption value="option-1">Option 1</MOOption>
    <MOOption value="option-2">Option 2</MOOption>
    <MOOption value="option-3">Option 3</MOOption>
  </MOSelect>
);

Setting the selection imperatively

To programmatically set the selection, update the value property as shown below. Note that the value must be an array when using the multiple option.

Option 1 Option 2 Option 3
Set 1 Set 2 Set 3 
<div class="selecting-example">
  <mo-select>
    <mo-option value="option-1">Option 1</mo-option>
    <mo-option value="option-2">Option 2</mo-option>
    <mo-option value="option-3">Option 3</mo-option>
  </mo-select>

  <br />

  <mo-button data-option="option-1">Set 1</mo-button>
  <mo-button data-option="option-2">Set 2</mo-button>
  <mo-button data-option="option-3">Set 3</mo-button>
</div>

<script>
  const container = document.querySelector('.selecting-example');
  const select = container.querySelector('mo-select');

  [...container.querySelectorAll('mo-button')].map(button => {
    button.addEventListener('click', () => {
      select.value = button.dataset.option;
    });
  });
</script>

import { useState } from 'react';
import { MOButton, MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => {
  const [value, setValue] = useState('option-1');

  return (
    <>
      <MOSelect value={value} onMoChange={event => setValue(event.target.value)}>
        <MOOption value="option-1">Option 1</MOOption>
        <MOOption value="option-2">Option 2</MOOption>
        <MOOption value="option-3">Option 3</MOOption>
      </MOSelect>

      <br />

      <MOButton onClick={() => setValue('option-1')}>Set 1</MOButton>
      <MOButton onClick={() => setValue('option-2')}>Set 2</MOButton>
      <MOButton onClick={() => setValue('option-3')}>Set 3</MOButton>
    </>
  );
};

Multiple

To allow multiple options to be selected, use the multiple attribute. With this option, value will be an array of strings instead of a string. It’s a good practice to use clearable when this option is enabled.

Option 1 Option 2 Option 3 Option 4 Option 5 Option 6 
<mo-select size="medium" placeholder="Select a few" multiple clearable>
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
  <mo-divider></mo-divider>
  <mo-option value="option-4">Option 4</mo-option>
  <mo-option value="option-5">Option 5</mo-option>
  <mo-option value="option-6">Option 6</mo-option>
</mo-select>

import { MODivider, MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect placeholder="Select a few" multiple clearable>
    <MOOption value="option-1">Option 1</MOOption>
    <MOOption value="option-2">Option 2</MOOption>
    <MOOption value="option-3">Option 3</MOOption>
    <MODivider />
    <MOOption value="option-4">Option 4</MOOption>
    <MOOption value="option-5">Option 5</MOOption>
    <MOOption value="option-6">Option 6</MOOption>
  </MOSelect>
);

Grouping options

Options can be grouped visually using menu labels and dividers.

Group 1 Option 1 Option 2 Option 3 Group 2 Option 4 Option 5 Option 6 
<mo-select placeholder="Select one">
  <mo-menu-label>Group 1</mo-menu-label>
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
  <mo-divider></mo-divider>
  <mo-menu-label>Group 2</mo-menu-label>
  <mo-option value="option-4">Option 4</mo-option>
  <mo-option value="option-5">Option 5</mo-option>
  <mo-option value="option-6">Option 6</mo-option>
</mo-select>

import { MODivider, MOOption, MOMenuLabel, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect placeholder="Select one">
    <MOMenuLabel>Group 1</MOMenuLabel>
    <MOOption value="option-1">Option 1</MOOption>
    <MOOption value="option-2">Option 2</MOOption>
    <MOOption value="option-3">Option 3</MOOption>
    <MODivider></MODivider>
    <MOMenuLabel>Group 2</MOMenuLabel>
    <MOOption value="option-4">Option 4</MOOption>
    <MOOption value="option-5">Option 5</MOOption>
    <MOOption value="option-6">Option 6</MOOption>
  </MOSelect>
);

Sizes

Use the size attribute to change a select’s size.

Option 1 Option 2 Option 3
Option 1 Option 2 Option 3
Option 1 Option 2 Option 3 
<mo-select placeholder="Small" size="small" multiple>
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

<br />

<mo-select placeholder="Medium" size="medium" multiple>
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

<br />

<mo-select placeholder="Large" size="large" multiple>
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

import { MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <>
    <MOSelect placeholder="Small" size="small" multiple>
      <MOOption value="option-1">Option 1</MOOption>
      <MOOption value="option-2">Option 2</MOOption>
      <MOOption value="option-3">Option 3</MOOption>
    </MOSelect>

    <br />

    <MOSelect placeholder="Medium" size="medium" multiple>
      <MOOption value="option-1">Option 1</MOOption>
      <MOOption value="option-2">Option 2</MOOption>
      <MOOption value="option-3">Option 3</MOOption>
    </MOSelect>

    <br />

    <MOSelect placeholder="Large" size="large" multiple>
      <MOOption value="option-1">Option 1</MOOption>
      <MOOption value="option-2">Option 2</MOOption>
      <MOOption value="option-3">Option 3</MOOption>
    </MOSelect>
  </>
);

Labels

Use the label attribute to give the select an accessible label. For labels that contain HTML, use the label slot instead.

Option 1 Option 2 Option 3 
<mo-select label="Select one">
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

import { MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect label="Select one">
    <MOOption value="option-1">Option 1</MOOption>
    <MOOption value="option-2">Option 2</MOOption>
    <MOOption value="option-3">Option 3</MOOption>
  </MOSelect>
);

Help text

Add descriptive help text to a select with the help-text attribute. For help texts that contain HTML, use the help-text slot instead.

Novice Intermediate Advanced 
<mo-select label="Experience" help-text="Please tell us your skill level.">
  <mo-option value="1">Novice</mo-option>
  <mo-option value="2">Intermediate</mo-option>
  <mo-option value="3">Advanced</mo-option>
</mo-select>

import { MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect label="Experience" help-text="Please tell us your skill level.">
    <MOOption value="1">Novice</MOOption>
    <MOOption value="2">Intermediate</MOOption>
    <MOOption value="3">Advanced</MOOption>
  </MOSelect>
);

Error and success text

If you wish to use third party error validation, use the errorText and successText attribute to show the error message. The error message will override the help text for the duration that it is visible.

If you wish to show the state without having a message, use the success and error boolean attributes instead.

Select this Do not select this 
<mo-select id="error" help-text="Select the correct option." label="Choose an option">
  <mo-option value="good">Select this</mo-option>
  <mo-option value="bad">Do not select this</mo-option>
</mo-select>

<script>
  const input = document.getElementById('error');
  input.addEventListener('mo-change', () => {
    if (input.value === 'good') {
      input.successText = 'Well chosen.';
      input.errorText = '';
    } else {
      input.errorText = 'You chose... poorly.';
      input.successText = '';
    }
  });
</script>

import { MOIcon, MOInput } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOInput helpText="Please enter the postal code in format '12345'." label="Postal code" placeholder="01300" />
);

Placement

The preferred placement of the select’s menu can be set with the placement attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are top and bottom.

Option 1 Option 2 Option 3 
<mo-select placement="top">
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
</mo-select>

import {
  MOOption,
  MOSelect
} from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <MOSelect placement="top">
    <MOOption value="option-1">Option 1</MOOption>
    <MOOption value="option-2">Option 2</MOOption>
    <MOOption value="option-3">Option 3</MOOption>
  </MODropdown>
);

Prefix & suffix icons

Use the prefix and suffix slots to add icons.

Option 1 Option 2 Option 3
Option 1 Option 2 Option 3
Option 1 Option 2 Option 3 
<mo-select placeholder="Small" size="small">
  <mo-icon name="home" slot="prefix"></mo-icon>
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
  <mo-icon name="chatting" slot="suffix"></mo-icon>
</mo-select>
<br />
<mo-select placeholder="Medium" size="medium">
  <mo-icon name="home" slot="prefix"></mo-icon>
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
  <mo-icon name="chatting" slot="suffix"></mo-icon>
</mo-select>
<br />
<mo-select placeholder="Large" size="large">
  <mo-icon name="home" slot="prefix"></mo-icon>
  <mo-option value="option-1">Option 1</mo-option>
  <mo-option value="option-2">Option 2</mo-option>
  <mo-option value="option-3">Option 3</mo-option>
  <mo-icon name="chatting" slot="suffix"></mo-icon>
</mo-select>

import { MOIcon, MOOption, MOSelect } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <>
    <MOSelect placeholder="Small" size="small">
      <MOIcon name="house" slot="prefix"></MOIcon>
      <MOOption value="option-1">Option 1</MOOption>
      <MOOption value="option-2">Option 2</MOOption>
      <MOOption value="option-3">Option 3</MOOption>
      <MOIcon name="chat" slot="suffix"></MOIcon>
    </MOSelect>
    <br />
    <MOSelect placeholder="Medium" size="medium">
      <MOIcon name="house" slot="prefix"></MOIcon>
      <MOOption value="option-1">Option 1</MOOption>
      <MOOption value="option-2">Option 2</MOOption>
      <MOOption value="option-3">Option 3</MOOption>
      <MOIcon name="chat" slot="suffix"></MOIcon>
    </MOSelect>
    <br />
    <MOSelect placeholder="Large" size="large">
      <MOIcon name="house" slot="prefix"></MOIcon>
      <MOOption value="option-1">Option 1</MOOption>
      <MOOption value="option-2">Option 2</MOOption>
      <MOOption value="option-3">Option 3</MOOption>
      <MOIcon name="chat" slot="suffix"></MOIcon>
    </MOSelect>
  </>
);

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Bundler React Script

To import this component using a bundler:

import '@metsooutotec/modes-web-components/dist/components/select/select.js';

To import this component as a React component:

import MOSelect from '@metsooutotec/modes-web-components/dist/react/select/';

To import this component using a script tag:

<script type="module" src="https://modes-web.metso.com/dist/components/cdn/components/select/select.js"></script>

Slots

Name Description
(default) The listbox options. Must be <mo-option> elements. You can use <mo-divider> to group items visually.
label The input’s label. Alternatively, you can use the label attribute.
prefix Used to prepend a presentational icon or similar element to the combobox.
clear-icon An icon to use in lieu of the default clear icon.
expand-icon The icon to show when the control is expanded and collapsed. Rotates on open and close.
help-text Text that describes how to use the input. Alternatively, you can use the help-text attribute.

Learn more about using slots.

Properties

Name Description Reflects Type Default
name The name of the select, submitted as a name/value pair with form data. string ''
value The current value of the select, submitted as a name/value pair with form data. When multiple is enabled, the value attribute will be a space-delimited list of values based on the options selected, and the value property will be an array. For this reason, values must not contain spaces. string | string[] ''
defaultValue The default value of the form control. Primarily used for resetting the form control. string | string[] ''
size The select’s size. 'small' | 'medium' | 'large' 'medium'
placeholder Placeholder text to show as a hint when the select is empty. string ''
multiple Allows more than one option to be selected. boolean false
maxOptionsVisible
max-options-visible 		The maximum number of selected options to show when multiple is true. After the maximum, ”+n” will be shown to indicate the number of additional items that are selected. Set to 0 to remove the limit. number 3
disabled Disables the select control. boolean false
listenToDocument Document event listeners are added directly on the document, instead of the components rootNode (which will limit functionality to inside that shadow root). boolean false
clearable Adds a clear button when the select is not empty. boolean false
allowWideDropdown Allows the dropdown to be wider than the select input field. boolean false
open Indicates whether or not the select is open. You can toggle this attribute to show and hide the menu, or you can use the show() and hide() methods and this attribute will reflect the select’s open state. boolean false
hoist Enable this option to prevent the listbox from being clipped when the component is placed inside a container with overflow: auto|scroll. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios. boolean false
label The select’s label. If you need to display HTML, use the label slot instead. string ''
error Renders the field in an error state boolean false
success Renders the field in a success state boolean false
errorText
error-text 		Error text to show in place of help text when input is invalid. string ''
successText
success-text 		Success text to show in place of help text when input is valid. string ''
placement The preferred placement of the select’s menu. Note that the actual placement may vary as needed to keep the listbox inside of the viewport. 'top' | 'bottom' 'bottom'
helpText
help-text 		The select’s help text. If you need to display HTML, use the help-text slot instead. string ''
form By default, form controls are associated with the nearest containing <form> element. This attribute allows you to place the form control outside of a form and associate it with the form that has this id. The form must be in the same document or shadow root for this to work. string ''
required The select’s required attribute. boolean false
getChip A function that customizes the chips to be rendered when multiple=true. The first argument is the option, the second is the current chip’s index. The function should return either a Lit TemplateResult or a string containing trusted HTML of the symbol to render at the specified value. (option: MOOption, index: number) => TemplateResult | string | HTMLElement -
validity Gets the validity state object - -
validationMessage Gets the validation message - -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
mo-change onMoChange Emitted when the control’s value changes. -
mo-clear onMoClear Emitted when the control’s value is cleared. -
mo-input onMoInput Emitted when the control receives input. -
mo-focus onMoFocus Emitted when the control gains focus. -
mo-blur onMoBlur Emitted when the control loses focus. -
mo-show onMoShow Emitted when the select’s menu opens. -
mo-after-show onMoAfterShow Emitted after the select’s menu opens and all animations are complete. -
mo-hide onMoHide Emitted when the select’s menu closes. -
mo-after-hide onMoAfterHide Emitted after the select’s menu closes and all animations are complete. -
mo-invalid onMoInvalid Emitted when the form control has been checked for validity and its constraints aren’t satisfied. -

Learn more about events.

Methods

Name Description Arguments
show() Shows the listbox. -
hide() Hides the listbox. -
checkValidity() Checks for validity but does not show a validation message. Returns true when valid and false when invalid. -
getForm() Gets the associated form, if one exists. -
reportValidity() Checks for validity and shows the browser’s validation message if the control is invalid. -
setCustomValidity() Sets a custom validation message. Pass an empty string to restore validity. message: string
focus() Sets focus on the control. options: FocusOptions
blur() Removes focus from the control. -

Learn more about methods.

Parts

Name Description
form-control The form control that wraps the label, input, and help text.
form-control-label The label’s wrapper.
form-control-input The select’s wrapper.
form-control-help-text The help text’s wrapper.
combobox The container the wraps the prefix, combobox, clear icon, and expand button.
prefix The container that wraps the prefix slot.
display-input The element that displays the selected option’s label, an <input> element.
listbox The listbox container where options are slotted.
chips The container that houses option chips when multiselect is used.
chip The individual chips that represent each multiselect option.
chip__base The chip’s base part.
chip__content The chip’s content part.
chip__remove-button The chip’s remove button.
chip__remove-button__base The chip’s remove button base part.
clear-button The clear button.
expand-icon The container that wraps the expand icon.
label__base The select label.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.