Search

Figma

Github

Storybook

Search provides the ability to narrow down data using a specialized TextField.

Anatomy

Search events

Required
Optional

Anatomy elements
#	Required	Element	Description
1		Container	Wrapper that includes the field, label, and assistive text.
2	No	Label	Describes what the Search covers. Accepts rich content such as icons or tooltips.
3	No	Icon	Leading icon that identifies the field as a search. Can be replaced or removed.
4		Field	Accepts user query. Can show a placeholder if empty.
5	No	Assistive text	Displays description or error text to aid the user.

Guidelines

When to use

Search narrows a large set of data based on user input. Use it when it would be faster for the user to filter by typing than scrolling or paging through a list.

Prefer a plain TextField when the value the user types is data to be saved rather than a query.

Search vs. Combobox and Filters

Search, Combobox, and Filters are three similar components that help the user narrow down data into digestible results. However, it's important to understand the difference between them as they are not interchangeable:

Search matches freeform text against data and returns results elsewhere on the page.
Combobox pairs a text input with a list of matching options, and the user selects one as their value.
Filters narrows a set by structured criteria the user builds from predefined fields and operators.

Best practices

Labels and placeholders

Search usually sits in a toolbar or page header, where a visible label competes with the controls around it. In those placements, we highly recommend providing an accessible label in place of a visible label. When outside of more compact layouts, a visible label is preferred.

Do: Rely on the icon and placeholder, with an accessible label for assistive technology.

Search templates

Don't: Add a visible label that repeats the placeholder.

Loading

Show the loading spinner while results are being fetched. Keep the field editable while it runs. Disabling the Search leaves the user unable to refine a slow query and dims the text they just typed.

Do: Keep the field editable and show the spinner while results load.

Don't: Disable the field while results load.

Results

Always show what the query returned. If there are no matches, use an EmptyState to describe the issue and offer a potential solution.

No results found

Try a shorter search term or check the spelling.

Do: Replace empty results with an explanation and a next step.

Customization

In adhering with Pluma's focus on flexibility, the Search component includes customization options beyond plain text. Customization is useful for adding richer label content or building custom assistive text.

Custom description

Descriptions are assistive text that display below the field. They can accept rich content including links.

Custom description with link

A description with an inline link directs users to additional resources.

Custom error

Error messages are assistive text that display below the field. They accept rich content, allowing the inclusion of links or formatted text that better help users resolve the issue.

Error with link

An error message with a link directs users to relevant documentation or support.

Custom label

The label accepts rich content, allowing supplementary elements such as icons or tooltips alongside the label text.

Search profiles

Label with tooltip

A tooltip explains what the query covers without lengthening the label.

Appearance

Icon

A magnifying glass icon leads the field by default and makes it recognizable as a search field without an explicit label. Replace it only when another icon better describes the scope or purpose of the search. Remove the icon when the Search component sits inside a menu or panel narrow enough that the icon crowds the text.

Icon

The search icon identifies the field at a glance and suits most placements.

No icon

Removing the icon gives the query more room in a narrow menu or panel.

Sizes

Search is available in two sizes: medium and small. Small is the default and fits the toolbars and page headers where search usually sits. Use medium when the Search is the primary control on the page or would best match other form control sizes.

Small

Small is the default and keeps the field compact in toolbars and filter rows.

Medium

Medium suits a Search that anchors a page or shares space with medium form controls.

Width

Search has a max width of space-3200 (256px) so it remains compact next to other toolbar controls. The Search's width can be set to expand the full container size if required.

Default width

The default cap keeps the field from stretching across a toolbar.

Full width

Widening the field ties it to the full-width content it filters.

Behaviors

States

Base

The Search has default input styling in its base resting state.

Hover

Border color updates on mouse hover to signal the field is interactive.

Focus

On keyboard focus, the field receives the standard 2px focus ring and the border color updates.

Active

Active styles apply while the user is interacting with the field.

Disabled

Disabled fields cannot be interacted with. Background and text color update to indicate the field is unavailable.

A spinner displays inside the field while results are being fetched.

Critical

The Search adopts critical styling to indicate there's an error. An error message displays below the field when set.

Clear button

A clear button appears at the end of the field once it has a value and resets the field when activated.

Clear button

The clear button resets the field and the results.

Content

Assistive text

Assistive text displays below the Search and tells the user something about the query they're entering. Assistive text comes in different forms including descriptions and error text.

Description

Use description text to name what the query matches or to explain syntax the field supports. Reach for a description when additional context is needed for the field. Short, complete sentences are preferred.

Do: Explain what the search query will match.

Don't: Repeat what the placeholder already says.

Error

Errors on a Search describe a query the field is unable to run. Explain what the field can't handle and what to change. Keep messages direct and concise.

For information on how to handle no results, see Results.

Do: Say what to change about the query.

Don't: Report the failure without a way to resolve it.

Labels

Write clear, concise labels that describe what data is being searched.

Search templates

Do: Describe the purpose of the field.

Don't: Label the field with the action alone.

Placeholders

Placeholders help the user complete a field by providing hints on what information it expects or how it should be formatted. Prefer using sentence case without a trailing ellipsis.

Do: Name the fields the query matches.

Don't: End a placeholder with an ellipsis.

Search

No results found

On this page