Best Practices

Components

Search vs. Filter, Text Input, and Combobox

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

Position

Position 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.
• Don't position the Search in the header of a container.

Behavior

Disabled state

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

Loading state

• Use a loading Search when the search takes more than a second to process.
• Don’t block merchants from editing the input during the loading state.
• The search process shouldn’t take longer than five seconds.

Feedback in a list

• The loading state with a spinner in the Search field should be the only feedback while the search is being processed. After the results load, the Search field should go back to its default state.
• Maintain the previous results visible until the new ones finish loading.
• Don’t show a Skeleton when processing a search.

Clearing or persisting results

• Clear results only when the merchant clicks on the clear Button with the <IconXCircle /> inside the Search field or manually erases the search terms.
• Maintain the previous results visible until the new ones finish loading.
• Don’t use local storage or cookies to store the search query.

Error feedback

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

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.

Supporting search operators

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.

Logic

• Ignore typos, capitalization, and accents.
• Support synonyms.
• Don’t include a Search field for each type of information that can be searched, support all of them in the same input.

Content

Placeholder text

• 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.
• 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.
• 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 on 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.

Icon

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