Select

BETA

Component demo

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
placeholder="Select an option..."
label="What is your favourite coffee?"
></ic-select>

<IcSelect
placeholder="Select an option..."
label="What is your favourite coffee?"
options={options}
onIcChange={(event)=>console.log(event.detail.value)}
/>

Select details

Props

All components also accept native properties supported by the DOM, such asclassName and style .

Name	Description	Default
Property label Attribute label	The label for the select. Required type: string
Property charactersUntilSuggestions Attribute characters-until-suggestions	This prop should not be used anymore. Deprecated	0
Property debounce Attribute debounce	The amount of time, in milliseconds, to wait to trigger the`icChange` event after each keystroke. type: number	0
Property disableFilter Attribute disable-filter	If`true` , the built in filtering will be disabled for a searchable variant. For example, if options will already be filtered from external source. type: boolean	false
Property disabled Attribute disabled	If`true` , the disabled state will be set. type: boolean	false
Property emptyOptionListText Attribute empty-option-list-text	The text displayed when there are no options in the option list. type: string	"No results found"
Property form Attribute form	The <form> element to associate the select with. type: string
Property formaction Attribute formaction	The URL that processes the information submitted by the select. It overrides the action attribute of the select's form owner. Does nothing if there is no form owner. This prop should only be used with searchable select and will only be applied if searchable is true. type: string
Property formenctype Attribute formenctype	The way the submitted form data is encoded. This prop should only be used with searchable select and will only be applied if searchable is true. type: string
Property formmethod Attribute formmethod	The HTTP method used to submit the form. This prop should only be used with searchable select and will only be applied if searchable is true. type: string
Property formnovalidate Attribute formnovalidate	If`true` , the form will not be validated when submitted. This prop should only be used with searchable select and will only be applied if searchable is true. type: boolean
Property formtarget Attribute formtarget	The place to display the response from submitting the form. It overrides the target attribute of the select's form owner. This prop should only be used with searchable select and will only be applied if searchable is true. type: string
Property fullWidth Attribute full-width	If`true` , the select element will fill the width of the container. This prop should only be used with searchable select and will only be applied if searchable is true. type: boolean	false
Property helperText Attribute helper-text	The helper text that will be displayed for additional field guidance. type: string	""
Property hideLabel Attribute hide-label	If`true` , the label will be hidden and the required label value will be applied as an aria-label. type: boolean	false
Property includeDescriptionsInSearch Attribute include-descriptions-in-search	If`true` , descriptions of options will be included when filtering options in a searchable select. Only applies to built in filtering. type: boolean	false
Property includeGroupTitlesInSearch Attribute include-group-titles-in-search	If`true` , group titles of grouped options will be included when filtering options in a searchable select. Only applies to built in filtering. type: boolean	false
Property loading Attribute loading	If`true` , the loading state will be triggered when fetching options asynchronously. type: boolean	false
Property loadingErrorLabel Attribute loading-error-label	The message displayed when external loading times out. type: string	"Loading Error"
Property loadingLabel Attribute loading-label	The message displayed whilst the options are being loaded externally. type: string	"Loading..."
Property name Attribute name	The name of the control, which is submitted with the form data. type: string	this.inputId
Property options Attribute	The possible selection options. type: IcMenuOption[]	[]
Property placeholder Attribute placeholder	The placeholder value to be displayed. type: string	"Select an option"
Property readonly Attribute readonly	If`true` , the readonly state will be set. type: boolean	false
Property required Attribute required	If`true` , the select will require a value. type: boolean	false
Property searchMatchPosition Attribute search-match-position	Whether the search string of the searchable select should match the start of or anywhere in the options. Only applies to built in filtering. type: IcSearchMatchPositions - "anywhere" \| "start"	"anywhere"
Property searchable Attribute searchable	If`true` , a searchable variant of the select will be displayed which can be typed in to filter options. type: boolean	false
Property selectOnEnter Attribute select-on-enter	If`true` , the icOptionSelect event will be fired on enter instead of ArrowUp and ArrowDown. type: boolean	false
Property showClearButton Attribute show-clear-button	If`true` , a button which clears the select input when clicked will be displayed. The button will always appear on the searchable select. type: boolean	false
Property size Attribute size	The size of the select component. type: IcSizes - "default" \| "large" \| "small"	"default"
Property small Attribute small	This prop should not be used anymore. Set prop `size` to "small" instead. Deprecated	false
Property timeout Attribute timeout	If using external filtering, set a timeout for when loading takes too long. type: number
Property validationStatus Attribute validation-status	The validation status - e.g. 'error' \| 'warning' \| 'success'. type: IcInformationStatusOrEmpty - "" \| "error" \| "success" \| "warning"	""
Property validationText Attribute validation-text	The text to display as the validation message. type: string	""
Property value Attribute value	The value of the select, reflected by the value of the currently selected option. For the searchable variant, the value is also reflected by the user input. type: string

Property

label

Attribute

label

The label for the select.

Required

type: string

Property

charactersUntilSuggestions

Attribute

characters-until-suggestions

This prop should not be used anymore.

Deprecated

Default: 0

Property

debounce

Attribute

debounce

The amount of time, in milliseconds, to wait to trigger theicChange event after each keystroke.

type: number

Default: 0

Property

disableFilter

Attribute

disable-filter

Iftrue , the built in filtering will be disabled for a searchable variant. For example, if options will already be filtered from external source.

type: boolean

Default: false

Property

disabled

Attribute

disabled

Iftrue , the disabled state will be set.

type: boolean

Default: false

Property

emptyOptionListText

Attribute

empty-option-list-text

The text displayed when there are no options in the option list.

type: string

Default: "No results found"

Property

form

Attribute

form

The <form> element to associate the select with.

type: string

Property

formaction

Attribute

formaction

The URL that processes the information submitted by the select. It overrides the action attribute of the select's form owner. Does nothing if there is no form owner. This prop should only be used with searchable select and will only be applied if searchable is true.

type: string

Property

formenctype

Attribute

formenctype

The way the submitted form data is encoded. This prop should only be used with searchable select and will only be applied if searchable is true.

type: string

Property

formmethod

Attribute

formmethod

The HTTP method used to submit the form. This prop should only be used with searchable select and will only be applied if searchable is true.

type: string

Property

formnovalidate

Attribute

formnovalidate

Iftrue , the form will not be validated when submitted. This prop should only be used with searchable select and will only be applied if searchable is true.

type: boolean

Property

formtarget

Attribute

formtarget

The place to display the response from submitting the form. It overrides the target attribute of the select's form owner. This prop should only be used with searchable select and will only be applied if searchable is true.

type: string

Property

fullWidth

Attribute

full-width

Iftrue , the select element will fill the width of the container. This prop should only be used with searchable select and will only be applied if searchable is true.

type: boolean

Default: false

Property

helperText

Attribute

helper-text

The helper text that will be displayed for additional field guidance.

type: string

Default: ""

Property

hideLabel

Attribute

hide-label

Iftrue , the label will be hidden and the required label value will be applied as an aria-label.

type: boolean

Default: false

Property

includeDescriptionsInSearch

Attribute

include-descriptions-in-search

Iftrue , descriptions of options will be included when filtering options in a searchable select. Only applies to built in filtering.

type: boolean

Default: false

Property

includeGroupTitlesInSearch

Attribute

include-group-titles-in-search

Iftrue , group titles of grouped options will be included when filtering options in a searchable select. Only applies to built in filtering.

type: boolean

Default: false

Property

Attribute

Iftrue , the loading state will be triggered when fetching options asynchronously.

type: boolean

Default: false

Property

loadingErrorLabel

Attribute

loading-error-label

The message displayed when external loading times out.

type: string

Default: "Loading Error"

Property

loadingLabel

Attribute

loading-label

The message displayed whilst the options are being loaded externally.

type: string

Default: "Loading..."

Property

name

Attribute

name

The name of the control, which is submitted with the form data.

type: string

Default: this.inputId

Property

options

Attribute

The possible selection options.

type: IcMenuOption[]

Default: []

Property

placeholder

Attribute

placeholder

The placeholder value to be displayed.

type: string

Default: "Select an option"

Property

readonly

Attribute

readonly

Iftrue , the readonly state will be set.

type: boolean

Default: false

Property

required

Attribute

required

Iftrue , the select will require a value.

type: boolean

Default: false

Property

searchMatchPosition

Attribute

search-match-position

Whether the search string of the searchable select should match the start of or anywhere in the options. Only applies to built in filtering.

type: IcSearchMatchPositions - "anywhere" | "start"

Default: "anywhere"

Property

searchable

Attribute

searchable

Iftrue , a searchable variant of the select will be displayed which can be typed in to filter options.

type: boolean

Default: false

Property

selectOnEnter

Attribute

select-on-enter

Iftrue , the icOptionSelect event will be fired on enter instead of ArrowUp and ArrowDown.

type: boolean

Default: false

Property

showClearButton

Attribute

show-clear-button

Iftrue , a button which clears the select input when clicked will be displayed. The button will always appear on the searchable select.

type: boolean

Default: false

Property

size

Attribute

size

The size of the select component.

type: IcSizes - "default" | "large" | "small"

Default: "default"

Property

small

Attribute

small

This prop should not be used anymore. Set prop `size` to "small" instead.

Deprecated

Default: false

Property

timeout

Attribute

timeout

If using external filtering, set a timeout for when loading takes too long.

type: number

Property

validationStatus

Attribute

validation-status

The validation status - e.g. 'error' | 'warning' | 'success'.

type: IcInformationStatusOrEmpty - "" | "error" | "success" | "warning"

Default: ""

Property

validationText

Attribute

validation-text

The text to display as the validation message.

type: string

Default: ""

Property

value

Attribute

value

The value of the select, reflected by the value of the currently selected option. For the searchable variant, the value is also reflected by the user input.

type: string

Slots

A slot allows for any type of element or markup to be passed into and rendered within a web component. This creates more flexibility than using a prop which must take a specific type of data.

Content can be slotted into a component by adding it as a top-level child of the component.

Slots can have a name to identify them. These specify which slot the content will be inserted into, and therefore where it will be rendered and how it will be used within the component. The name of the slot to be used can be specified by passing it via a slot attribute on the slotted content.

Name	Description
Slot icon	Content will be placed to the left of the select text input.

CSS Custom Properties

Name	Description
--ic-z-index-menu	z-index of select menu
--input-width	Width of the input field

--ic-z-index-menu z-index of select menu

--input-width Width of the input field

Events

All components also accept native events supported by the DOM, such as onClick and onKeyDown .

Name	Description	Signature
Web component icBlur React onIcBlur	Emitted when the select loses focus.	void
Web component icChange React onIcChange	Emitted when the value changes.	IcValueEventDetail
Web component icClear React onIcClear	Emitted when the clear button is clicked.	void
Web component icClose React onIcClose	Emitted when the select options menu is closed.	void
Web component icFocus React onIcFocus	Emitted when the select gains focus.	void
Web component icInput React onIcInput	Emitted when a keyboard input occurred.	IcValueEventDetail
Web component icOpen React onIcOpen	Emitted when the select options menu is opened.	void
Web component icOptionSelect React onIcOptionSelect	Emitted when an option is highlighted within the menu. Highlighting a menu item will also trigger an `icChange/onIcChange` due to the value being updated.	IcOptionSelectEventDetail
Web component icRetryLoad React onIcRetryLoad	Emitted when the 'retry loading' button is clicked for a searchable variant.	IcValueEventDetail

Web component

icBlur

React

onIcBlur

Emitted when the select loses focus.

void

Web component

icChange

React

onIcChange

Emitted when the value changes.

IcValueEventDetail

Web component

icClear

React

onIcClear

Emitted when the clear button is clicked.

void

Web component

icClose

React

onIcClose

Emitted when the select options menu is closed.

void

Web component

icFocus

React

onIcFocus

Emitted when the select gains focus.

void

Web component

icInput

React

onIcInput

Emitted when a keyboard input occurred.

IcValueEventDetail

Web component

icOpen

React

onIcOpen

Emitted when the select options menu is opened.

void

Web component

icOptionSelect

React

onIcOptionSelect

Emitted when an option is highlighted within the menu. Highlighting a menu item will also trigger an `icChange/onIcChange` due to the value being updated.

IcOptionSelectEventDetail

Web component

icRetryLoad

React

onIcRetryLoad

Emitted when the 'retry loading' button is clicked for a searchable variant.

IcValueEventDetail

Methods

Name	Description	Signature
Method setFocus	Sets focus on the input box.	setFocus() => Promise<void>

Method

setFocus

Sets focus on the input box.

setFocus() => Promise<void>

Variants

With clear button, descriptions, helper text and custom placeholder

Interactive example

What is your favourite coffee?

Select one option from the list

Web component

React

<ic-select
label="What is your favourite coffee?"
placeholder="Select an option..."
helper-text="Select one option from the list"
show-clear-button="true"
searchable="true"
></ic-select>

<IcSelect
label="What is your favourite coffee?"
options={options}
placeholder="Select an option…"
helperText="Select one option from the list"
showClearButton
searchable
onIcChange={(event)=>console.log(event.detail.value)}
/>

Disabled

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
disabled="true"
></ic-select>

<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
options={options}
disabled
onIcChange={(event)=>console.log(event.detail.value)}
/>

Options disabled

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
></ic-select>

<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
options={options}
onIcChange={(event)=>console.log(event.detail.value)}
/>

Size small

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
label="What is your favourite coffee?"
size="small"
></ic-select>

<IcSelect
label="What is your favourite coffee?"
options={options}
onIcChange={(event)=>console.log(event.detail.value)}
size="small"
/>

Hidden label

Interactive example

Web component

React

<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
hide-label="true"
></ic-select>

<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
options={options}
hideLabel
onIcChange={(event)=>console.log(event.detail.value)}
/>

Groups

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
></ic-select>

<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
options={options}
onIcChange={(event)=>console.log(event.detail.value)}
/>

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
></ic-select>

<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
options={options}
onIcChange={(event)=>console.log(event.detail.value)}
/>

Validation

Interactive example

What is your favourite coffee?

Coffee available

What is your favourite coffee?

Only a few left

What is your favourite coffee?

Coffee unavailable

Web component

React

<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
validation-status="success"
validation-text="Coffee available"
value="americano"
id="1"
></ic-select>
<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
validation-status="warning"
validation-text="Only a few left"
value="cappuccino"
id="2"
></ic-select>
<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
validation-status="error"
validation-text="Coffee unavailable"
value="mocha"
id="3"
></ic-select>

<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
value="americano"
options={options}
validationStatus="success"
validationText="Coffee available"
onIcChange={(event)=>console.log(event.detail.value)}
/>
<IcSelect
placeholder="Select an option…"l
abel="What is your favourite coffee?"
value="cappuccino"
options={options}
validationStatus="warning"
validationText="Only a few left"
onIcChange={(event)=>console.log(event.detail.value)}
/>
<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
value="mocha"
options={options}
validationStatus="error"
validationText="Coffee unavailable"
onIcChange={(event)=>console.log(event.detail.value)}
/>

Custom elements in options

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
placeholder="Select an option..."
label="What is your favourite coffee?"
></ic-select>

<IcSelect
placeholder="Select an option..."
label="What is your favourite coffee?"
options={options}
onIcChange={(event)=>console.log(event.detail.value)}
/>

Searchable

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
searchable="true"
></ic-select>

<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
options={options}
searchable
onIcChange={(event)=>console.log(event.detail.value)}
/>

Searchable – with descriptions included in search

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
searchable="true"
include-description-in-search="true"
></ic-select>

<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
options={options}
searchable
includeDescriptionsInSearch
onIcChange={(event)=>console.log(event.detail.value)}
/>

Searchable – with group titles included in search

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
searchable="true"
include-group-titles-in-search="true"
></ic-select>

<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
options={options}
searchable
includeGroupTitlesInSearch
onIcChange={(event)=>console.log(event.detail.value)}
/>

Custom filtering example

This example shows how to filter data asynchronously when the value in the select field changes. The data is mocked and displayed after a one second delay, but could be replaced with a call to an API or database.

Interactive example

What is your favourite coffee?

Web component

React

<ic-select
placeholder="Select an option…"
label="What is your favourite coffee?"
searchable="true"
debounce="300"
disable-filter="true"
id="external-filter-select"
characters-until-suggestions="2"
></ic-select>

<IcSelect
placeholder="Select an option…"
label="What is your favourite coffee?"
debounce={300}
searchable
disableFilter
options={results}
onIcOptionSelect={(event)=>setSelectedValue(event.detail.value)}
onIcClear={()=>setResults([])}
onIcChange={changeHandler}
/>

Last reviewed 31 May 2024 .

Component demo

Interactive example

Select details

Props

Slots

CSS Custom Properties

Events

Methods

Variants

With clear button, descriptions, helper text and custom placeholder

Interactive example

Disabled

Interactive example

Options disabled

Interactive example

Size small

Interactive example

Hidden label

Interactive example

Groups

Interactive example

Recommended

Interactive example

Validation

Interactive example

Custom elements in options

Interactive example

Searchable

Interactive example

Searchable – with descriptions included in search

Interactive example

Searchable – with group titles included in search

Interactive example

Custom filtering example

Interactive example