Select

Show navigation section

Component demo

Interactive example

Web component

React

Show full code

<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 debounce Attribute debounce	The amount of time, in milliseconds, to wait to trigger the`icInput` event after each keystroke. type: number	0
Property disableAutoFiltering Attribute disable-auto-filtering	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 - string \| undefined
Property fullWidth Attribute full-width	If`true` , the select will fill the width of the container. 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 multiple Attribute multiple	If`true` , multiple options can be selected. type: boolean	false
Property name Attribute name	The name of the control, which is submitted with the form data. type: string	this.inputId
Property options	The possible selection options. type: IcMenuOption[] - export interface IcMenuOption { description?: string; disabled?: boolean; recommended?: boolean; children?: IcMenuOption[]; loading?: boolean; timedOut?: boolean; [key: string]: any; element?: { component: any; ariaLabel: string; }; icon?: any; hideLabel?: boolean; htmlProps?: Record<string, any>; }	[]
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. This functionality is only available on the single-select variant of the select component. type: boolean	false
Property selectOnEnter Attribute select-on-enter	If`true` , the icOptionSelect event will be fired on enter instead of ArrowUp and ArrowDown on the single select. 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. type: IcSizes - "large" \| "medium" \| "small"	"medium"
Property theme Attribute theme	Sets the theme color to the dark or light theme color. "inherit" will set the color based on the system settings or ic-theme component. type: IcThemeMode - "dark" \| "inherit" \| "light"	"inherit"
Property timeout Attribute timeout	If using external filtering, set a timeout for when loading takes too long. type: number - number \| undefined
Property validationAriaLive Attribute validation-aria-live	The value of the`aria-live` attribute on the validation message. type: IcAriaLive - "assertive" \| "off" \| "polite"	"polite"
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. For the multi-select variant, the value must be an array of option values. type: string \| string[] \| null - null \| string \| string[]	null

Property

label

Attribute

label

The label for the select.

Required

type: string

Property

debounce

Attribute

debounce

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

type: number

Default: 0

Property

disableAutoFiltering

Attribute

disable-auto-filtering

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 - string | undefined

Property

fullWidth

Attribute

full-width

Iftrue , the select will fill the width of the container.

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

multiple

Attribute

multiple

Iftrue , multiple options can be selected.

type: boolean

Default: false

Property

name

Attribute

name

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

type: string

Default: this.inputId

Property

options

The possible selection options.

type: IcMenuOption[] - export interface IcMenuOption { description?: string; disabled?: boolean; recommended?: boolean; children?: IcMenuOption[]; loading?: boolean; timedOut?: boolean; [key: string]: any; element?: { component: any; ariaLabel: string; }; icon?: any; hideLabel?: boolean; htmlProps?: Record<string, any>; }

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. This functionality is only available on the single-select variant of the select component.

type: boolean

Default: false

Property

selectOnEnter

Attribute

select-on-enter

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

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.

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

Default: "medium"

Property

theme

Attribute

theme

Sets the theme color to the dark or light theme color. "inherit" will set the color based on the system settings or ic-theme component.

type: IcThemeMode - "dark" | "inherit" | "light"

Default: "inherit"

Property

timeout

Attribute

timeout

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

type: number - number | undefined

Property

validationAriaLive

Attribute

validation-aria-live

The value of thearia-live attribute on the validation message.

type: IcAriaLive - "assertive" | "off" | "polite"

Default: "polite"

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. For the multi-select variant, the value must be an array of option values.

type: string | string[] | null - null | string | string[]

Default: null

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 helper-text	Content is set as the helper text for the select.
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
--menu-width	Width of the dropdown menu

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

--input-width Width of the input field

--menu-width Width of the dropdown menu

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.	IcMultiValueEventDetail
Web component icClear React onIcClear	Emitted when the clear or clear all 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.	IcMultiValueEventDetail
Web component icOpen React onIcOpen	Emitted when the select options menu is opened.	void
Web component icOptionDeselect React onIcOptionDeselect	Emitted when `multiple` is `true` and an option is deselected.	IcOptionSelectEventDetail
Web component icOptionSelect React onIcOptionSelect	Emitted when an option is selected. Selecting an option 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.	IcMultiValueEventDetail

Web component

icBlur

React

onIcBlur

Emitted when the select loses focus.

void

Web component

icChange

React

onIcChange

Emitted when the value changes.

IcMultiValueEventDetail

Web component

icClear

React

onIcClear

Emitted when the clear or clear all 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.

IcMultiValueEventDetail

Web component

icOpen

React

onIcOpen

Emitted when the select options menu is opened.

void

Web component

icOptionDeselect

React

onIcOptionDeselect

Emitted when `multiple` is `true` and an option is deselected.

IcOptionSelectEventDetail

Web component

icOptionSelect

React

onIcOptionSelect

Emitted when an option is selected. Selecting an option 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.

IcMultiValueEventDetail

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

Web component

React

Show full code

<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

Web component

React

Show full code

<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

Web component

React

Show full code

<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)}
/>

With icon

Interactive example

Web component

React

Show full code

<ic-select
label="What is your favourite coffee?"
>
<svg
slot="icon"
xmlns="http://www.w3.org/2000/svg"
height="24"
viewBox="0 0 24 24"
width="24"
fill="#000000"
>
<pathd="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
</svg>
</ic-select>

<IcSelect
label="What is your favourite coffee?"
options={options}
onIcChange={(event)=>console.log(event.detail.value)}
>
<SlottedSVG
slot="icon"
xmlns="http://www.w3.org/2000/svg"
height="24"
viewBox="0 0 24 24"
width="24"
fill="#000000"
>
<pathd="M2,21H20V19H2M20,8H18V5H20M20,3H4V13A4,4 0 0,0 8,17H14A4,4 0 0,0 18,13V10H20A2,2 0 0,0 22,8V5C22,3.89 21.1,3 20,3Z"/>
</SlottedSVG>
</IcSelect>

Sizes

Interactive example

Web component

React

Show full code

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

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

Required

Interactive example

Web component

React

Show full code

<ic-select
label="What is your favourite coffee?"
required="true"
></ic-select>

<IcSelect
label="What is your favourite coffee?"
options={options}
required
/>

Hidden label

Interactive example

Web component

React

Show full code

<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

Web component

React

Show full code

<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

Web component

React

Show full code

<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

Web component

React

Show full code

<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…"
label="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

Web component

React

Show full code

<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

Web component

React

Show full code

<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

Web component

React

Show full code

<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

Web component

React

Show full code

<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)}
/>

Multi-select

Interactive example

Web component

React

Show full code

<ic-select
id="select-default"
label="What are your favourite types of coffee?"
multiple="true"
></ic-select>

<IcSelect
label="What are your favourite types of coffee?"
value={["Ame","Fil","Moc"]}
options={options}
onIcChange={(event)=>console.log(event.detail.value)}
onIcOptionSelect={(event)=>console.log(event.detail.value)}
onIcOptionDeselect={(event)=>console.log(event.detail.value)}
multiple
/>

Multi-select - Read-only

Make the multi-select read-only by using thereadonly prop. Use thevalue prop to set which options are selected and will be displayed when it is read-only.

Interactive example

Web component

React

Show full code

<ic-select
id="select-default"
label="What are your favourite types of coffee?"
multiple="true"
readonly="true"
></ic-select>

<IcSelect
value={["Cap","Fla","Moc"]}
label="What are your favourite types of coffee?"
options={options}
multiple
readonly
/>

Multi-select - Groups

Display options in groups by passing an array of child options to thechildren property of a parent option. The parent option will be rendered as the title of the group.

Interactive example

Web component

React

Show full code

<ic-select
id="select-default"
label="What are your favourite types of coffee?"
multiple="true"
></ic-select>

<IcSelect
label="What are your favourite types of coffee?"
options={options}
multiple
/>

Multi-select - Disabled options

Disable certain options by setting thedisabled property totrue for each option.

Interactive example

Web component

React

Show full code

<ic-select
id="select-default"
label="What are your favourite types of coffee?"
multiple="true"
></ic-select>

<IcSelect
label="What are your favourite types of coffee?"
options={options}
onIcChange={(event)=>console.log(event.detail.value)}
onIcOptionSelect={(event)=>console.log(event.detail.value)}
onIcOptionDeselect={(event)=>console.log(event.detail.value)}
multiple
/>

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

Web component

React

Show full code

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

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

Last reviewed 24 March 2025 .

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

With icon

Interactive example

Sizes

Interactive example

Required

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

Multi-select

Interactive example

Multi-select - Read-only

Interactive example

Multi-select - Groups

Interactive example

Multi-select - Disabled options

Interactive example

Custom filtering example

Interactive example