Search Field

For development, import SearchField from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

Four elements work together in the Search Field:

Placeholder text
Search icon
Search value
Clear button

Options

Configure Search Field for different scenarios:

Sizes

Size	Height
Small	32px
Medium	40px
Large	48px

Behavior

Search Field has distinct visual states and handles clearing and overflow.

Visual States

Clearing

The clear button follows web standards:

Shows when there is an input value
Not focusable, only clickable

Overflow

Long text scrolls horizontally within the container. The visible portion follows the cursor.

Usage Guidelines

Standard	Requirement
DoSearching a Table	Place Search Field with a Table so users can find rows by keyword.
DoSearching a catalog of items	Help users find an item in a catalog that is too large to browse.
DoComplex Dialog selection	Use Search Field inside the complex Dialog selection pattern to narrow the options.
Don’tSmall datasets	Don’t add search when the dataset is small or the content is easy to find on the page. Users can scan it directly.

Alternatives

Search Field vs Combobox

Use Combobox when users select from an overlayed list of options, typically in a form field. Use Search Field for traditional search experiences, filtering lists on the page, tables, large datasets, or results that need additional filtering.

How to Use

Combine Search Field with other UI elements for a complete search experience. Customize it to fit your needs.

General search results guidance

Keep the search term present after running search
Show the number of results when possible
Show filters when possible
Leverage Skeleton loaders when waiting for results to populate
Include a “no results” empty state when possible

Show the number of results when possible

Consider creating sections to organize results.
Consider adding filters to narrow down results.
If there are additional results that are not shown, consider adding a link to a page with all available results.
If the results become too complicated, consider using a Dialog over a Popover.

Content

Placeholder text and search results should clearly communicate the search context.

Keyboard Interaction

Navigate the Search Field using standard keyboard controls.

Accessibility

Search Field doesn’t have a label, so place it near related content to make its purpose clear. For more guidance on form field labels and context, see input field context association best practices.

Code

Implementation
SearchField Props

Common Examples

import { SearchField } from "@servicetitan/anvil2";

function ExampleComponent() {
  return <SearchField />;
}

Controlling search inputs

The value of search inputs are uncontrolled by default. To control a search input, use the value prop.

Uncontrolled

Controlled

Form Example

The SearchField component uses an HTML input and so can be used within an HTML form the same way that a regular HTML input element can.

React Accessibility

Add aria-label or aria-labelledby so that screen readers can properly announce what this is searching.For more guidance on form field labels and context, see input field context association best practices.

<SearchField
  autoComplete="off"
  disabled={false}
  size="medium"
  onClear={() => console.log("Cleared")}
  value="search term"
  onChange={(e) => console.log(e.target.value)}
  aria-label="Search"
/>

`SearchField` Props

The SearchField component accepts any valid HTML input props, other than prefix, required, children, as well as the following:

React.HTMLInputAutoCompleteAttribute

default:"off"

boolean

default:"false"

() => void

Callback when the clear button is clicked.

"small" | "medium" | "large"

default:"medium"

Concepts & Guidelines

Anvil2

Resources

Search Field - Web

Anatomy

Options

Sizes

Behavior

Visual States

Clearing

Overflow

Usage Guidelines

Alternatives

Search Field vs Combobox

How to Use

General search results guidance

Show the number of results when possible

Content

Keyboard Interaction

Accessibility

Code

Common Examples

Controlling search inputs

Uncontrolled

Controlled

Form Example

React Accessibility

`SearchField` Props

​Anatomy

​Options

​Sizes

​Behavior

​Visual States

​Clearing

​Overflow

​Usage Guidelines

​Alternatives

​Search Field vs Combobox

​How to Use

​General search results guidance

Show the number of results when possible

​Dropdown with results

​Content

​Keyboard Interaction

​Accessibility

​Code

​Common Examples

​Controlling search inputs

​Uncontrolled

​Controlled

​Form Example

​React Accessibility

​SearchField Props

Anatomy

Options

Sizes

Behavior

Visual States

Clearing

Overflow

Usage Guidelines

Alternatives

Search Field vs Combobox

How to Use

General search results guidance

Dropdown with results

Content

Keyboard Interaction

Accessibility

Code

Common Examples

Controlling search inputs

Uncontrolled

Controlled

Form Example

React Accessibility

`SearchField` Props