Intelligence Community Design System ICDS Get started Accessibility Styles Components Patterns Community
Show navigation section

Select

Guidance Code Accessibility

Component demo

Interactive example

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

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 theicInput event after each keystroke.

type: number
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
false
Property disabled
Attribute disabled

Iftrue , 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

Iftrue , 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

Iftrue , 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

Iftrue , 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

Iftrue , 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

Iftrue , 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

Iftrue , 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

Iftrue , the readonly state will be set.

type: boolean
false
Property required
Attribute required

Iftrue , 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

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
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
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
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 thearia-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 loading
Attribute loading

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