Search

What is this?

Search inputs allow merchants to filter by free form content that can't be classified in predefined options.

Loading

Disabled

Internationalized Placeholder

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.

Value:

DebouncedValue:

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

Value:

DebouncedValue:

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

Components

When to choose a Filter, a Text Input or a Combobox instead of a Search?

• Choose the Filter component when the content can be classified in predefined options that can be chosen as criteria to filter items.
• Choose the Text Input component to fill free form content that will be submitted as part of a form.
• Choose the Combobox component (single or multiple) to contextually filter a list of options and then submit the selected ones as part of a form.

Position

Where should Search be positioned in a container?

Considering left-to-right interfaces, follow these recommendations:

• Position the Search directly above the content that will be filtered.
• The Search should always be in the top left of a container.
• Use the DataView component to correctly position the Search.

What to avoid:

• Don't position the Search in the header of a container.

Behavior

When to use a disabled Search?

Avoid using a disabled Search. Use the DataView component instead, which automatically hides the Search input when the list is empty.

When to use a loading Search?

• Use a loading Search when the search takes more than a second to process.

What to avoid:

• Don’t block merchants from editing the input during the loading state.
• The search process shouldn’t take longer than five seconds.

What should be the searching feedback in a list?

• The loading state with a spinner in the Search Input should be the only feedback while the search is being processed. After the results load, the Search input should go back to its default state.
• Maintain the previous results visible until the new ones finish loading.

What to avoid:

• Don’t show a Skeleton when processing a search.

When to clear or persist search results?

• Clear results only when the merchant clicks on the Button with the <IconXCircle /> inside the Search input or manually erases the search terms.
• Maintain the previous results visible until the new ones finish loading.

What to avoid:

• Don’t use local storage or cookies to store the search query.

What should be the search error feedback?

When the search doesn’t return results due to an error, use the DataView component to correctly display the feedback.

What should be the no results feedback?

When the search works but returns empty because there are no results matching the query, use the DataView component to correctly display the feedback.

When to support search operators for advanced search?

Avoid supporting search operators. Even though they are powerful, they aren’t discoverable and can be complex for most merchants. Prefer using Filters as a way to combine criteria.

What should be the search logic?

• Ignore typos, capitalization and accents.
• Support synonyms.

What to avoid:

• Don’t include a Search input for each type of information that can be searched, support all of them in the same input.

Content

What should be the placeholder text of a Search?

In most cases, the experience should be intuitive enough not to need instructions on what should be searched. Only customize the placeholder text after UX research to understand the merchants’ needs, following these guidelines:

• Describe the properties that can be searched when they go beyond the merchant’s expectations. For example, Search for Name, ID or Ref ID.
• Considering localization, prioritize the properties that are most relevant according to UX research. For example, Search for Name, ID, Ref ID and more.
• When a Table column has a label for the same property, reuse the name to maintain consistency.

What to avoid:

• Don’t use placeholder text to include important information, since it will be hidden when the merchant types search terms.
• Avoid redundancy. Instead of writing Product name and Product ID in a Products page, write Name and ID.
• Avoid writing more than 36 characters.
• Don’t customize the width of the Search input on DataView to make the custom placeholder fit.
• Avoid adding support to search for properties that are not being shown for each result.

What should be the icon of a Search?

Always show <IconMagnifyingGlass /> to ensure the Search input is easily recognizable by merchants.

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