Search bar - Intelligence Community Design System

Show navigation section

Component demo

Interactive example

Web component

React

Show full code

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

<IcSearchBar
label="What is your favourite coffee?"
options={options}
onIcChange={(ev)=>console.log(ev.detail.value)}
onIcSubmitSearch={(ev)=>console.log(ev.detail.value)}
placeholder="Start typing to search…"
/>

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 - string \| undefined	"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 \| undefined	"off"
Property autocomplete Attribute autocomplete	The state of autocompletion the browser can apply on the text value. type: IcAutocompleteTypes - IcAutocompleteTypes \| undefined	"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" \| undefined	"off"
Property autofocus Attribute autofocus	If`true` , the form control will have input focus when the page loads. type: boolean \| undefined	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 - number \| undefined	2
Property debounce Attribute debounce	The amount of time, in milliseconds, to wait to trigger the`icChange` event after each keystroke. type: number - number \| undefined	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. If`true` , all options provided will be displayed. type: boolean - boolean \| undefined	false
Property disabled Attribute disabled	If`true` , the disabled state will be set. type: boolean - boolean \| undefined	false
Property emptyOptionListText Attribute empty-option-list-text	The text displayed when there are no options in the option list. type: string - string \| undefined	"No results found"
Property focusOnLoad Attribute focus-on-load	If`true` , the search bar will be focused when component loaded. type: boolean - boolean \| undefined	false
Property fullWidth Attribute full-width	Specify whether the search bar fills the full width of the container. If`true` , this overrides the --input-width CSS variable. type: boolean - boolean \| undefined	false
Property helperText Attribute helper-text	The helper text that will be displayed for additional field guidance. type: string - string \| undefined	""
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 - boolean \| undefined	false
Property labelField Attribute label-field	The custom name for the label field to correspond with the IcMenuOption type. type: string - string \| undefined	"label"
Property loading Attribute loading	Trigger loading state when fetching options asynchronously type: boolean - boolean \| undefined	false
Property loadingErrorLabel Attribute loading-error-label	Change the message displayed when external loading times out. type: string - string \| undefined	"Loading Error"
Property loadingLabel Attribute loading-label	Change the message displayed whilst the options are being loaded externally. type: string - string \| undefined	"Loading..."
Property name Attribute name	The name of the control, which is submitted with the form data. type: string - string \| undefined	this.inputId
Property options	The suggested search options. type: IcMenuOption[] - IcMenuOption[] \| undefined	[]
Property placeholder Attribute placeholder	The placeholder value to display. type: string - string \| undefined	"Search"
Property readonly Attribute readonly	If`true` , the readonly state will be set. type: boolean - boolean \| undefined	false
Property required Attribute required	If`true` , the search bar will require a value. type: boolean - boolean \| undefined	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" \| undefined	"navigation"
Property size Attribute size	The size of the search bar component. type: IcSizesNoLarge - "medium" \| "small" \| undefined	"medium"
Property spellcheck Attribute spellcheck	If`true` , the value of the search will have its spelling and grammar checked. type: boolean \| undefined	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" \| undefined	"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 - string \| undefined	""
Property valueField Attribute value-field	The custom name for the value field to correspond with the IcMenuOption type. type: string - string \| undefined	"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 - string | undefined

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

Default: "off"

Property

autocomplete

Attribute

autocomplete

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

type: IcAutocompleteTypes - IcAutocompleteTypes | undefined

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

Default: "off"

Property

autofocus

Attribute

autofocus

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

type: boolean | undefined

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

Default: 2

Property

debounce

Attribute

debounce

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

type: number - number | undefined

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

Default: false

Property

disabled

Attribute

disabled

Iftrue , the disabled state will be set.

type: boolean - boolean | undefined

Default: false

Property

emptyOptionListText

Attribute

empty-option-list-text

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

type: string - string | undefined

Default: "No results found"

Property

focusOnLoad

Attribute

focus-on-load

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

type: boolean - boolean | undefined

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

Default: false

Property

helperText

Attribute

helper-text

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

type: string - string | undefined

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

Default: false

Property

labelField

Attribute

label-field

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

type: string - string | undefined

Default: "label"

Property

Attribute

Trigger loading state when fetching options asynchronously

type: boolean - boolean | undefined

Default: false

Property

loadingErrorLabel

Attribute

loading-error-label

Change the message displayed when external loading times out.

type: string - string | undefined

Default: "Loading Error"

Property

loadingLabel

Attribute

loading-label

Change the message displayed whilst the options are being loaded externally.

type: string - string | undefined

Default: "Loading..."

Property

name

Attribute

name

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

type: string - string | undefined

Default: this.inputId

Property

options

The suggested search options.

type: IcMenuOption[] - IcMenuOption[] | undefined

Default: []

Property

placeholder

Attribute

placeholder

The placeholder value to display.

type: string - string | undefined

Default: "Search"

Property

readonly

Attribute

readonly

Iftrue , the readonly state will be set.

type: boolean - boolean | undefined

Default: false

Property

required

Attribute

required

Iftrue , the search bar will require a value.

type: boolean - boolean | undefined

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

Default: "navigation"

Property

size

Attribute

size

The size of the search bar component.

type: IcSizesNoLarge - "medium" | "small" | undefined

Default: "medium"

Property

spellcheck

Attribute

spellcheck

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

type: boolean | undefined

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

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

Default: ""

Property

valueField

Attribute

value-field

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

type: string - string | undefined

Default: "value"

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

Web component

React

Show full code

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

<IcSearchBar
placeholder="Start typing to search…"
label="What is your favourite coffee?"
disableAutoFiltering
options={options}
/>
<br/>
<IcTypography>
<p>All options will be displayed as you type</p>
</IcTypography>

With helper text

Interactive example

Web component

React

Show full code

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

<IcSearchBar
placeholder="Start typing to search…"
label="What is your favourite coffee?"
helperText="Coffee options will be displayed as you type."
options={options}
/>

With hidden label

Interactive example

Web component

React

Show full code

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

<IcSearchBar
placeholder="Start typing to search…"
label="What is your favourite coffee?"
hideLabel
options={options}
/>

Disabled

Interactive example

Web component

React

Show full code

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

<IcSearchBar
label="What is your favourite coffee?"
disabled
options={options}
/>

Size small

Interactive example

Web component

React

Show full code

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

<IcSearchBar
label="What is your favourite coffee?"
size="small"
options={options}
/>

Theme

Interactive example

Web component

React

Show full code

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

<IcSearchBar
label="What is your favourite coffee?"
options={options}
placeholder="Start typing to search…"
theme="dark"
/>

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

Web component

React

Show full code

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

<IcSearchBar
placeholder="Start typing to search…"
label="What is your favourite coffee?"
debounce={300}
disableAutoFiltering
options={results}
onIcChange={changeHandler}
/>

Last reviewed 31 May 2024 .