Search field usage guidelines

Usage guidelines API

Search field allows users to enter words or phrases to quickly find relevant content. It can also be used as a filter, narrowing results in a list or page section.

When to use

When users need to quickly find items in a large dataset.
When content is not easily browsable through scrolling or filtering alone.
When users already have an idea of what they are looking for (searching by name, ID, keyword).
When instant feedback is valuable, paired with autocomplete or suggestions to speed up discovery.

When not to use

When the dataset is small and easily browsed, use a select or combo box.
When users don’t know what to search for, use a combination of additional filters.
For complex queries requiring multiple parameters, consider advanced search or filter panels instead.
As a primary navigation method. Search field should support structured navigation, not replace it.

import { SearchField } from '@cimpress-ui/react';

export default function Demo() {
  return <SearchField label="Search" placeholder="Enter your query" />;
}

Formatting and layout

Placement

For application-wide search, place the search field in the app header.
For searches that are specific to the content of a page or section, place the search field at the top of that area.

Spacing

Search fields should have at least 16px of horizontal and vertical spacing between them and other elements.

Content writing

Label

Label should be clear and concise, immediately communicating the field’s purpose to the user.
Do use a short description of just one or two words for the label such as “Search products”.

Placeholder text

Placeholder text can be used to provide an example of user input but should not duplicate the label text.
Placeholder text is optional and should only be used where more context is necessary for the user to understand.

Description text

A description can contain an explanation and search suggestions, which should help users to understand what kind of information they can search.
Do not provide unnecessary description text when the purpose of the search field is obvious.
End the description text with a period or equivalent punctuation mark. This helps screen reader users understand where the description ends, and it improves readability for all users.

Error text

Do provide clear and concise error messaging.
Do explain the issue and let the user know what they need to do to resolve it. Error messages should always provide users with a solution or a path to resolving the error.
Error messages should use language that is easily understood rather than complex technical terms.
End the error message with a period or equivalent punctuation mark. This helps screen reader users understand where the error message ends, and it improves readability for all users.

Behaviors

Dynamic search

“Dynamic search” refers to a situation in which the search results are updated live as the user types in the search field. A dynamic search field can be placed in the header, or above a list or table. In this scenario, all data is usually already loaded or prefetched, but in some cases results may be fetched from the server while typing.

Use dynamic search when:

filtering options in a list
filtering table rows
searching/filtering within a page section (e.g., properties, addresses, tags)
speed and efficiency are critical
showing a list of orders/products when typing

Action search

“Action search” refers to a situation in which the user needs to explicitly trigger the search by pressing the Enter key or pressing a button. In this scenario, results are usually shown on a new page, often with filters, sorting, and advanced options.

Use action search when:

users are exploring and don’t know exactly what to search for
there’s need for search query cost optimizations

Clearing the field

The contents of a search field can be cleared by using the built-in “Clear” icon button, or by pressing the Escape key.