OLYSENSE Design System

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

Option 1

Option 2

Option 3

<ods-select hoist value='option-1'>
  <ods-option value="option-1">Option 1</ods-option>
  <ods-option value="option-2">Option 2</ods-option>
  <ods-option value="option-3">Option 3</ods-option>
</ods-select>

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <OdsSelect hoist value='option-1'>
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
    </OdsSelect>
  )
}

export default Example;

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

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

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <OdsSelect label="Select one" hoist>
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
    </OdsSelect>
  )
}

export default Example;

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.

Option 1

Option 2

Option 3

<ods-select label="Select one" help-text="Please tell us your skill level." hoist>
  <ods-option value="option-1">Option 1</ods-option>
  <ods-option value="option-2">Option 2</ods-option>
  <ods-option value="option-3">Option 3</ods-option>
</ods-select>

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <OdsSelect label="Select one" help-text="Please tell us your skill level." hoist>
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
    </OdsSelect>
  )
}

export default Example;

Use the placeholder attribute to add a placeholder.

Option 1

Option 2

Option 3

<ods-select label="Select one" placeholder="Select one"s hoist>
  <ods-option value="option-1">Option 1</ods-option>
  <ods-option value="option-2">Option 2</ods-option>
  <ods-option value="option-3">Option 3</ods-option>
</ods-select>

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <OdsSelect placeholder="Select one" hoist>
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
    </OdsSelect>
  )
}

export default Example;

Use the required attribute to specify the input is a required field when using within a form.

Option 1

Option 2

Option 3

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

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <OdsSelect required label="Select one" hoist>
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
    </OdsSelect>
  )
}

export default Example;

Use the disabled attribute to disable a select.

Option 1

Option 2

Option 3

<ods-select label="Select one" placeholder="Disabled" required disabled hoist help-text="Sample help text">
  <ods-option value="option-1">Option 1</ods-option>
  <ods-option value="option-2">Option 2</ods-option>
  <ods-option value="option-3">Option 3</ods-option>
</ods-select>

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <OdsSelect label="Select one" placeholder="Disabled" required disabled hoist help-text="Sample help text">
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
    </OdsSelect>
  )
}

export default Example;

Use the error-text attribute to customize the error message shown. Read more about error validation here .

<form novalidate>
    <ods-select required error-text="Sample error text" label="Select one" hoist>
        <ods-option value="option-1">Option 1</ods-option>
        <ods-option value="option-2">Option 2</ods-option>
        <ods-option value="option-3">Option 3</ods-option>
    </ods-select>
</form>

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <form noValidate>
      <OdsSelect required error-text="Sample error text" label="Select one" hoist>
        <OdsOption value="option-1">Option 1</OdsOption>
        <OdsOption value="option-2">Option 2</OdsOption>
        <OdsOption value="option-3">Option 3</OdsOption>
      </OdsSelect>
    </form>
  )
}

export default Example;

Use the clearable attribute to make the control clearable. The clear button only appears when an option is selected.

Option 1

Option 2

Option 3

<ods-select value="option-1" clearable hoist>
  <ods-option value="option-1">Option 1</ods-option>
  <ods-option value="option-2">Option 2</ods-option>
  <ods-option value="option-3">Option 3</ods-option>
</ods-select>

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <OdsSelect value="option-1" clearable hoist>
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
    </OdsSelect>
  )
}

export default Example;

To allow multiple options to be selected, use the multiple attribute. It’s a good practice to use clearable when this option is enabled. To set multiple values at once, set value to a space-delimited list of values.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

<ods-select label="Select a Few" value="option-1 option-2 option-3" hoist multiple clearable>
  <ods-option value="option-1">Option 1</ods-option>
  <ods-option value="option-2">Option 2</ods-option>
  <ods-option value="option-3">Option 3</ods-option>
  <ods-option value="option-4">Option 4</ods-option>
  <ods-option value="option-5">Option 5</ods-option>
  <ods-option value="option-6">Option 6</ods-option>
</ods-select>

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <OdsSelect label="Select a Few" value={["option-1", "option-2", "option-3"]} hoist multiple clearable>
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
      <OdsOption value="option-4">Option 4</OdsOption>
      <OdsOption value="option-5">Option 5</OdsOption>
      <OdsOption value="option-6">Option 6</OdsOption>
    </OdsSelect>
  )
}

export default Example;

Use <sl-divider> to group listbox items visually. You can also use <small> to provide labels, but they won’t be announced by most assistive devices.

Section 1

Option 1

Option 2

Option 3

Section 2

Option 4

Option 5

Option 6

<ods-select hoist>
  <small>Section 1</small>
  <ods-option value="option-1">Option 1</ods-option>
  <ods-option value="option-2">Option 2</ods-option>
  <ods-option value="option-3">Option 3</ods-option>
  <ods-divider></ods-divider>
  <small>Section 2</small>
  <ods-option value="option-4">Option 4</ods-option>
  <ods-option value="option-5">Option 5</ods-option>
  <ods-option value="option-6">Option 6</ods-option>
</ods-select>

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <OdsSelect hoist>
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
      <OdsOption value="option-4">Option 4</OdsOption>
      <OdsOption value="option-5">Option 5</OdsOption>
      <OdsOption value="option-6">Option 6</OdsOption>
    </OdsSelect>
  )
}

export default Example;

The preferred placement of the select’s listbox 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

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

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';

const Example = () => {
  return (
    <OdsSelect placement="top" hoist>
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
    </OdsSelect>
  )
}

export default Example;

You can listen for the ods-input event to determine when a value is select. To see other input events check out the events below . You can also see how selects are used in forms by checking out the form section .

Option 1

Option 2

Option 3

<ods-select id="input-example" hoist>
  <ods-option value="option-1">Option 1</ods-option>
  <ods-option value="option-2">Option 2</ods-option>
  <ods-option value="option-3">Option 3</ods-option>
</ods-select>

<script>
  const input = document.getElementById('input-example');

  const onInputHandler = (event) => {
    const target = event.target;

    alert(`Selected value is ${target.value}`);
  };

  input.addEventListener('ods-input', (event) => onInputHandler(event));
</script>

import { OdsSelect } from '@ods/components/react.select';
import { OdsOption } from '@ods/components/react.option';
import { OdsInputEvent } from '@ods/components/react';

export const Example = () => {
  const onInputHandler = (event: OdsInputEvent) => {
    const target = event.target as HTMLSelectElement;

    alert(`Selected value is ${target.value}`);
  };

  return (
    <OdsSelect onOdsInput={onInputHandler} hoist>
      <OdsOption value="option-1">Option 1</OdsOption>
      <OdsOption value="option-2">Option 2</OdsOption>
      <OdsOption value="option-3">Option 3</OdsOption>
    </OdsSelect>
  )
}

export default Example;

Importing

import '@ods/components/web.select';

Note: You only need to import a web component once in your code, as it registers itself globally when defined, allowing you to use it anywhere within your application without needing to re-import it each time you want to use the component.

Slots

Name	Description
(default)	The listbox options. Must be `<ods-option>` elements. You can use `<ods-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.

Properties

Please note, both DOM properties and HTML attributes are shown in the table below. Unless otherwise specified, the property and attribute names are identical.

Property/Attribute	Type	Default
name	string	''
value	string \| string[]	''
defaultValue	string \| string[]	''
placeholder	string	''
multiple	boolean	false
maxOptionsVisible max-options-visible	number	3
disabled	boolean	false
clearable	boolean	false
open	boolean	false
hoist	boolean	false
filled	boolean	false
pill	boolean	false
label	string	''
placement	'top' \| 'bottom'	'bottom'
helpText help-text	string	''
errorText error-text	string	''
form	string	''
required	boolean	false
getTag	(option: OdsOption, index: number) => TemplateResult \| string \| HTMLElement
validity
validationMessage

Events

React Event	Description	Event Detail
ods-change	Emitted when the control's value changes.	--
ods-clear	Emitted when the control's value is cleared.	--
ods-input	Emitted when the control receives input.	--
ods-focus	Emitted when the control gains focus.	--
ods-blur	Emitted when the control loses focus.	--
ods-show	Emitted when the select's menu opens.	--
ods-after-show	Emitted after the select's menu opens and all animations are complete.	--
ods-hide	Emitted when the select's menu closes.	--
ods-after-hide	Emitted after the select's menu closes and all animations are complete.	--
ods-invalid	Emitted when the form control has been checked for validity and its constraints aren't satisfied.	--

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.	--
focus()	Sets focus on the control.	--
blur()	Removes focus from the control.	--

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.
form-control-error-text	The error 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.
tags	The container that houses option tags when `multiselect` is used.
tag	The individual tags that represent each multiselect option.
tag__base	The tag's base part.
tag__content	The tag's content part.
tag__remove-button	The tag's remove button.
tag__remove-button__base	The tag's remove button base part.
clear-button	The clear button.
expand-icon	The container that wraps the expand icon.

Dependencies

This component automatically imports the following dependencies.

ods-icon
ods-icon-button
ods-popup
ods-tag

Select

Examples

Basic

Label

Help Text

Placeholders

Required

Disabled

Error

Clearable

Multiple

Grouping

Placement

Handling An Event

Importing

Slots

Properties

Events

Methods

Parts

Dependencies