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

Search bar

Guidance Code Accessibility

Component demo

Interactive example

<ic-search-barlabel="What is your favourite coffee?"placeholder="Start typing to search…"></ic-search-bar>

Search bar 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 search bar.

Required type: string
Property assistiveHintText
Attribute assistive-hint-text

The hint text for the hidden assistive description element.

type: string
"When autocomplete results are available use the up and down arrows to choose and press enter to select"
Property autocapitalize
Attribute autocapitalize

The automatic capitalisation of the text value as it is entered/edited by the user. Available options: "off", "none", "on", "sentences", "words", "characters".

type: string
"off"
Property autocomplete
Attribute autocomplete

The state of autocompletion the browser can apply on the text value.

type: IcAutocompleteTypes - "name" | "on" | "off" | "honorific-prefix" | "given-name" | "additional-name" | "family-name" | "honorific-suffix" | "nickname" | "email" | "username" | "new-password" | "current-password" | "one-time-code" | "organization-title" | "organization" | "street-address" | "address-line1" | "address-line2" | "address-line3" | "address-level4" | "address-level3" | "address-level2" | "address-level1" | "country" | "country-name" | "postal-code" | "cc-name" | "cc-given-name" | "cc-additional-name" | "cc-family-name" | "cc-number" | "cc-exp" | "cc-exp-month" | "cc-exp-year" | "cc-csc" | "cc-type" | "transaction-currency" | "transaction-amount" | "language" | "bday" | "bday-day" | "bday-month" | "bday-year" | "sex" | "tel" | "tel-country-code" | "tel-national" | "tel-area-code" | "tel-local" | "tel-extension" | "impp" | "url" | "photo"
"off"
Property autocorrect
Attribute autocorrect

The state of autocorrection the browser can apply when the user is entering/editing the text value.

type: IcAutocorrectStates - "off" | "on"
"off"
Property autofocus
Attribute autofocus

Iftrue , the form control will have input focus when the page loads.

type: boolean
false
Property charactersUntilSuggestion
Attribute characters-until-suggestion

The number of characters until suggestions appear. The submit button will be disabled until the inputted value is equal to or greater than this number.

type: number
2
Property debounce
Attribute debounce

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

type: number
0
Property disableAutoFiltering
Attribute disable-auto-filtering

Specify whether to disable the built in filtering. For example, if options will already be filtered from external source. Iftrue , all options provided will be displayed.

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 focusOnLoad
Attribute focus-on-load

Iftrue , the search bar will be focused when component loaded.

type: boolean
false
Property fullWidth
Attribute full-width

Specify whether the search bar fills the full width of the container. Iftrue , this overrides the --input-width CSS variable.

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 labelField
Attribute label-field

The custom name for the label field to correspond with the IcMenuOption type.

type: string
"label"
Property loading
Attribute loading

Trigger loading state when fetching options asynchronously

type: boolean
false
Property loadingErrorLabel
Attribute loading-error-label

Change the message displayed when external loading times out.

type: string
"Loading Error"
Property loadingLabel
Attribute loading-label

Change 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

The suggested search options.

type: IcMenuOption[]
[]
Property placeholder
Attribute placeholder

The placeholder value to display.

type: string
"Search"
Property preventFormSubmitOnSearch
Attribute prevent-form-submit-on-search

Iftrue the parent form will not submit when the icSubmitSearch event fires.

type: boolean
false
Property readonly
Attribute readonly

Iftrue , the readonly state will be set.

type: boolean
false
Property required
Attribute required

Iftrue , the search bar will require a value.

type: boolean
false
Property searchMode
Attribute search-mode

Specify the mode search bar uses to search.navigation allows for quick lookups of a set of values,query allows for more general searches.

type: IcSearchBarSearchModes - "navigation" | "query"
"navigation"
Property size
Attribute size

The size of the search bar component.

type: IcSizesNoLarge - "medium" | "small"
"medium"
Property spellcheck
Attribute spellcheck

Iftrue , the value of the search will have its spelling and grammar checked.

type: boolean
false
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 value
Attribute value

The value of the search input.

type: string
""
Property valueField
Attribute value-field

The custom name for the value field to correspond with the IcMenuOption type.

type: string
"value"
Property label
Attribute label

The label for the search bar.

Required type: string
Property assistiveHintText
Attribute assistive-hint-text

The hint text for the hidden assistive description element.

type: string
Default: "When autocomplete results are available use the up and down arrows to choose and press enter to select"
Property autocapitalize
Attribute autocapitalize

The automatic capitalisation of the text value as it is entered/edited by the user. Available options: "off", "none", "on", "sentences", "words", "characters".

type: string
Default: "off"
Property autocomplete
Attribute autocomplete

The state of autocompletion the browser can apply on the text value.

type: IcAutocompleteTypes - "name" | "on" | "off" | "honorific-prefix" | "given-name" | "additional-name" | "family-name" | "honorific-suffix" | "nickname" | "email" | "username" | "new-password" | "current-password" | "one-time-code" | "organization-title" | "organization" | "street-address" | "address-line1" | "address-line2" | "address-line3" | "address-level4" | "address-level3" | "address-level2" | "address-level1" | "country" | "country-name" | "postal-code" | "cc-name" | "cc-given-name" | "cc-additional-name" | "cc-family-name" | "cc-number" | "cc-exp" | "cc-exp-month" | "cc-exp-year" | "cc-csc" | "cc-type" | "transaction-currency" | "transaction-amount" | "language" | "bday" | "bday-day" | "bday-month" | "bday-year" | "sex" | "tel" | "tel-country-code" | "tel-national" | "tel-area-code" | "tel-local" | "tel-extension" | "impp" | "url" | "photo"
Default: "off"
Property autocorrect
Attribute autocorrect

The state of autocorrection the browser can apply when the user is entering/editing the text value.

type: IcAutocorrectStates - "off" | "on"
Default: "off"
Property autofocus
Attribute autofocus

Iftrue , the form control will have input focus when the page loads.

type: boolean
Default: false
Property charactersUntilSuggestion
Attribute characters-until-suggestion

The number of characters until suggestions appear. The submit button will be disabled until the inputted value is equal to or greater than this number.

type: number
Default: 2
Property debounce
Attribute debounce

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

type: number
Default: 0
Property disableAutoFiltering
Attribute disable-auto-filtering

Specify whether to disable the built in filtering. For example, if options will already be filtered from external source. Iftrue , all options provided will be displayed.

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 focusOnLoad
Attribute focus-on-load

Iftrue , the search bar will be focused when component loaded.

type: boolean
Default: false
Property fullWidth
Attribute full-width

Specify whether the search bar fills the full width of the container. Iftrue , this overrides the --input-width CSS variable.

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 labelField
Attribute label-field

The custom name for the label field to correspond with the IcMenuOption type.

type: string
Default: "label"
Property loading
Attribute loading

Trigger loading state when fetching options asynchronously

type: boolean
Default: false
Property loadingErrorLabel
Attribute loading-error-label

Change the message displayed when external loading times out.

type: string
Default: "Loading Error"
Property loadingLabel
Attribute loading-label

Change 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

The suggested search options.

type: IcMenuOption[]
Default: []
Property placeholder
Attribute placeholder

The placeholder value to display.

type: string
Default: "Search"
Property preventFormSubmitOnSearch
Attribute prevent-form-submit-on-search

Iftrue the parent form will not submit when the icSubmitSearch event fires.

type: boolean
Default: false
Property readonly
Attribute readonly

Iftrue , the readonly state will be set.

type: boolean
Default: false
Property required
Attribute required

Iftrue , the search bar will require a value.

type: boolean
Default: false
Property searchMode
Attribute search-mode

Specify the mode search bar uses to search.navigation allows for quick lookups of a set of values,query allows for more general searches.

type: IcSearchBarSearchModes - "navigation" | "query"
Default: "navigation"
Property size
Attribute size

The size of the search bar component.

type: IcSizesNoLarge - "medium" | "small"
Default: "medium"
Property spellcheck
Attribute spellcheck

Iftrue , the value of the search will have its spelling and grammar checked.

type: boolean
Default: false
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 value
Attribute value

The value of the search input.

type: string
Default: ""
Property valueField
Attribute value-field

The custom name for the value field to correspond with the IcMenuOption type.

type: string
Default: "value"

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.

Read more about slots .


Name Description
Slot helper-text
Content is set as the helper text for the search bar.
Slot helper-text
Content is set as the helper text for the search bar.

CSS Custom Properties

Name Description
--ic-z-index-menu z-index of search bar menu
--ic-z-index-menu z-index of search bar menu

Events

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

Name Description Signature
Web component icChange
React onIcChange
Emitted when the value has changed.
IcValueEventDetail
Web component icClear
React onIcClear
Emitted when value is cleared with clear button
void
Web component icInput
React onIcInput
Emitted when a keyboard input occurred.
IcValueEventDetail
Web component icKeydown
React onIcKeydown
Emitted when a keydown event occurred.
{ event: KeyboardEvent; }
Web component icMenuChange
React onIcMenuChange
Emitted when the state of the menu changes (i.e. open or close)
IcMenuChangeEventDetail
Web component icOptionSelect
React onIcOptionSelect
Emitted when option is highlighted within the menu
IcOptionSelectEventDetail
Web component icRetryLoad
React onIcRetryLoad
Emitted when the 'retry loading' button is clicked
IcMultiValueEventDetail
Web component icSearchBarBlur
React onIcSearchBarBlur
Emitted when blur is invoked from ic-search-bar
IcSearchBarBlurEventDetail
Web component icSearchBarFocus
React onIcSearchBarFocus
Emitted when focus is invoked from ic-search-bar
IcValueEventDetail
Web component icSubmitSearch
React onIcSubmitSearch
Emitted when the search value has been submitted
IcValueEventDetail
Web component icChange
React onIcChange
Emitted when the value has changed.
IcValueEventDetail
Web component icClear
React onIcClear
Emitted when value is cleared with clear button
void
Web component icInput
React onIcInput
Emitted when a keyboard input occurred.
IcValueEventDetail
Web component icKeydown
React onIcKeydown
Emitted when a keydown event occurred.
{ event: KeyboardEvent; }
Web component icMenuChange
React onIcMenuChange
Emitted when the state of the menu changes (i.e. open or close)
IcMenuChangeEventDetail
Web component icOptionSelect
React onIcOptionSelect
Emitted when option is highlighted within the menu
IcOptionSelectEventDetail
Web component icRetryLoad
React onIcRetryLoad
Emitted when the 'retry loading' button is clicked
IcMultiValueEventDetail
Web component icSearchBarBlur
React onIcSearchBarBlur
Emitted when blur is invoked from ic-search-bar
IcSearchBarBlurEventDetail
Web component icSearchBarFocus
React onIcSearchBarFocus
Emitted when focus is invoked from ic-search-bar
IcValueEventDetail
Web component icSubmitSearch
React onIcSubmitSearch
Emitted when the search value has been submitted
IcValueEventDetail

Methods

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

Variants

With options (no filtering)

Interactive example


All options will be displayed as you type
<ic-search-bar
placeholder="Start typing to search…"
label="What is your favourite coffee?"
disable-auto-filtering="true"
></ic-search-bar>
<br>
<ic-typography>
<p>All options will be displayed as you type</p>
</ic-typography>

With helper text

Interactive example

<ic-search-bar
placeholder="Start typing to search…"
label="What is your favourite coffee?"
helper-text="Coffee options will be displayed as you type."
></ic-search-bar>

With hidden label

Interactive example

<ic-search-bar
placeholder="Start typing to search…"
label="What is your favourite coffee?"
hide-label="true"
></ic-search-bar>

Disabled

Interactive example

<ic-search-bar
label="What is your favourite coffee?"
disabled="true"
></ic-search-bar>

Size small

Interactive example

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

Theme

Interactive example

<ic-search-bar
label="What is your favourite coffee?"
placeholder="Start typing to search…"
theme="dark"
></ic-search-bar>

Custom filtering example

This example shows how to filter data asynchronously when the value in the input 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

<ic-search-bar
placeholder="Start typing to search…"
label="What is your favourite coffee?"
debounce="300"
disable-auto-filtering="true"
></ic-search-bar>

Last reviewed 31 May 2024 .
Navigated to Search bar - Intelligence Community Design System