Search

What is this?

Search enables users to specify a word, phrase, or term to find relevant pieces of content.

Loading

ReferenceError: Box is not defined

Disabled

ReferenceError: Box is not defined

Internationalized Placeholder

ReferenceError: Box is not defined

Debounce

A common UX pattern is to filter the collections (or make a query) while the user types the input. To do that performatively, we often use debounced values. You can use the useSearchState hook which stores a debounced value for you!

ReferenceError: Box is not defined

Persisted state in query params

You can persist the search value within the browser's query params using the `useQuerySearchState` hook, instead of `useSearchState`. The application should be wrapped by `QueryStateProvider`. Watch how your url changes (note that the persisted value is the debounced value).

ReferenceError: Box is not defined

Usage

Remember that you can use the useSearchState or useSearchQueryState hooks to help you managing the Search state.

import { Search, useSearchState } from '@vtex/admin-ui'

function Example() {
  const [value, setValue] = useState('')
  const [loading, setLoading] = useState(false)

  return (
    <Search
      value={value}
      onChange={(e) => setValue(e.target.value)}
      onClear={() => setValue('')}
      loading={loading}
    />
  )
}

Props

In the following sections you can check the properties of the Search component and its hooks.

Search

You can use all the props accepted by the `form` JSX element.

Name	Type	Description	Required	Default
onClear	() => void	Clears the input value	🚫	-
value	string	Input value	🚫	''
onChange	ChangeEventHandler<HTMLInputElement>	Event triggered when input value changes	🚫	-
loading	boolean	Whether the search is loading or not	🚫	false

useSearchState Params

Name	Type	Description	Required	Default
initialValue	string	Initial input value	🚫	''
defaultValue	string	Value set in the clean action	🚫	''
timeout	number	Debounce timeout in ms	🚫	250

useSearchState return

Name	Type	Description
debouncedValue	string	Input value with debouce
setValue	(value: string) => void	Sets the value state
onClear	() => void	Clears the input value
value	string	Input value
onChange	ChangeEventHandler<HTMLInputElement>	Event triggered when input value changes
getInputProps	() => { value, onClear, onChange }	It returns the necessary properties to the Search works

useQuerySearchState Params

Name	Type	Description	Required	Default
defaultValue	string	Value set in the clean action	🚫	''
initiallyLoading	boolean	If is initially loading	🚫	false
timeout	number	Debounce timeout in ms	🚫	250

useQuerySearchState Return

The object returned from the state hook is the same as useSearchState.

Accessibility

To ensure that assistive technology can interact safely with the Search component, you must define the aria-label property when using multiple Search components in the same page. Remember that each aria-label should be unique and if you're dealing with i18n, you must translate them.

import { Search, useSearchState } from '@vtex/admin-ui'

function Example() {
  const { getInputProps } = useSearchState()

  return (
    <Page>
      <Search {...getInputProps()} aria-label="Unique and meaningful label" />
      ...
      <Search
        {...getInputProps()}
        aria-label="Another unique and meaningful label"
      />
    </Page>
  )
}

• What is this?
• Loading
• Disabled
• Internationalized Placeholder
• Debounce
• Persisted state in query params