Multi-select

CANARY

Component demo

Interactive example

Web component

React

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

<IcSelectWithMulti
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
/>

Select with multi 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	[DEPRECATED] This prop should not be used anymore. type: number	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 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 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. type: IcSizes - "default" \| "large" \| "small"	"default"
Property small Attribute small	[DEPRECATED] This prop should not be used anymore. Set prop`size` to "small" instead. type: boolean	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. For the multi-select variant, the value must be an array of option values. type: string \| string[]

Property

label

Attribute

label

The label for the select.

Required

type: string

Property

charactersUntilSuggestions

Attribute

characters-until-suggestions

**[DEPRECATED]** This prop should not be used anymore.

type: number

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

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

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.

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

Default: "default"

Property

small

Attribute

small

**[DEPRECATED]** This prop should not be used anymore. Set propsize to "small" instead.

type: boolean

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

type: string | string[]

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.	IcValueEventDetail
Web component icClear React onIcClear	Emitted when the clear button is clicked.	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 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.	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

icFocus

React

onIcFocus

Emitted when the select gains focus.

void

Web component

icInput

React

onIcInput

Emitted when a keyboard input occurred.

IcValueEventDetail

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.

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

Default value

Show options as pre-selected by setting thevalue prop to an array containing the values of these options.

Interactive example

Web component

React

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

<IcSelectWithMulti
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
/>

With clear button

Display a clear button by using theshowClearButton prop.

This will appear when the user has selected some options and allow them to easily clear their selection.

Interactive example

Web component

React

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

<IcSelectWithMulti
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
showClearButton
/>

With descriptions

Display extra information about the options by providing a description using thedescription property for each option.

Interactive example

Web component

React

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

<IcSelectWithMulti
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
/>

Helper text

Display helper text to provide additional information by using thehelperText prop.

Interactive example

Web component

React

<ic-select-with-multi
id="select-default"
label="What are your favourite types of coffee?"
helper-text="Select some options from the list"
multiple="true"
></ic-select-with-multi>

<IcSelectWithMulti
label="What are your favourite types of coffee?"
helperText="Select some options from the list"
options={options}
onIcChange={(event)=>console.log(event.detail.value)}
onIcOptionSelect={(event)=>console.log(event.detail.value)}
onIcOptionDeselect={(event)=>console.log(event.detail.value)}
multiple
/>

Sizes

Set the size of the multi-select by using thesize prop. This prop takes the valuessmall ,default orlarge . Depending on the chosen size, the prop will apply styling to increase or decrease the amount of spacing within the component. Thedefault variant is seen in the first default example.

Interactive example

Web component

React

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

<IcSelectWithMulti
label="What are your favourite types of coffee?"
options={options}
multiple
size="small"
/>
<IcSelectWithMulti
label="What are your favourite types of coffee?"
options={options}
multiple
/>
<IcSelectWithMulti
label="What are your favourite types of coffee?"
options={options}
multiple
size="large"
/>

Disabled

Disable the multi-select and prevent user interaction by using thedisabled prop.

Interactive example

Web component

React

<ic-select-with-multi
label="What are your favourite types of coffee?"
multiple="true"
disabled="true"
></ic-select-with-multi>

<IcSelectWithMulti
label="What are your favourite types of coffee?"
multiple
disabled
/>

Disabled options

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

Interactive example

Web component

React

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

<IcSelectWithMulti
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
/>

Hide label

Hide the visible label for the multi-select by using thehideLabel prop.

Interactive example

Web component

React

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

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

Required

Inform the user that the multi-select is a required field by using therequired prop. This will display an asterisk next to the label and apply thearia-required attribute.

Interactive example

Web component

React

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

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

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

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

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

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

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

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

Interactive example

Web component

React

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

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

Validation

Display a validation status and message by using thevalidation-status andvalidation-message props. Thevalidation-status prop takes the valuessuccess ,warning orerror .

Interactive example

Web component

React

<ic-select-with-multi
id="select-default"
label="What are your favourite types of coffee?"
multiple="true"
validation-status="success"
validation-text="Coffee available"
></ic-select-with-multi>

<IcSelectWithMulti
label="What are your favourite types of coffee?"
options={options}
multiple
validation-status="success"
validation-text="Coffee available"
/>

Loading with error

Display the loading state by using theloading prop. The multi-select will show a loading error after the amount of time specified using thetimeout prop has elapsed.

Interactive example

Web component

React

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

<IcSelectWithMulti
label="What are your favourite types of coffee?"
options={options}
multiple
loading
timeout={1000}
/>

Last reviewed 5 June 2024 .

Component demo

Interactive example

Select with multi details

Props

CSS Custom Properties

Events

Methods

Variants

Default value

Interactive example

With clear button

Interactive example

With descriptions

Interactive example

Helper text

Interactive example

Sizes

Interactive example

Disabled

Interactive example

Disabled options

Interactive example

Hide label

Interactive example

Required

Interactive example

Read-only

Interactive example

Groups

Interactive example

Recommended

Interactive example

Validation

Interactive example

Loading with error

Interactive example