Skip to main content

SearchField

The SearchField component captures search terms for filtering and search functionality. Use it to enable inline search within specific sections or lists, like filtering products or searching customers.

Support
Targets (10)

Supported targets

Use cases

  • Inline filtering: Enable filtering of lists, tables, or content sections.
  • Quick search: Provide search inputs for finding items within catalogs or data sets.
  • Real-time filtering: Support filtering as users type with automatic clear functionality.
  • Contextual search: Implement search within product variants, order items, or customer lists.

Anchor to examplesExamples

Anchor to example-enable-search-with-a-search-fieldEnable search with a search field

Enable search functionality using a SearchField component. This example shows a basic search field with placeholder text.

Enable search with a search field

Enable search with a search field

<s-search-field placeholder="Search" />

Anchor to example-handle-search-input-eventsHandle search input events

Subscribe to search input events to respond when merchants enter search terms. This example demonstrates handling onChange and onInput events for real-time search functionality, debounced filtering, or triggering search API calls as merchants type their queries.

Handle search input events

<s-search-field
placeholder="Search products..."
value=""
onInput={(event) => console.log('Input:', event.currentTarget.value)}
onChange={(event) => console.log('Change:', event.currentTarget.value)}
onFocus={(event) => console.log('Search focused')}
onBlur={(event) => console.log('Search blurred')}
/>

Anchor to propertiesProperties

Configure the following properties on the SearchField component.

Anchor to disabled
disabled
boolean
Default: false

Disables the field, disallowing any interaction.

Anchor to id
id
string

A unique identifier for the element.

Anchor to placeholder
placeholder
string

A short hint that describes the expected value of the field.

Anchor to value
value
string

The current value for the field. If omitted, the field will be empty.

Anchor to eventsEvents

The SearchField component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to blur
blur
(event: <"s-search-field">) => void

Callback when the field loses focus.

Anchor to change
change
(event: <"s-search-field">) => void

Callback when the field loses focus after the user changes the value in the field.

Anchor to focus
focus
(event: <"s-search-field">) => void

Callback when the field is focused.

Anchor to input
input
(event: <"s-search-field">) => void

Callback when the user changes the value in the field.

Anchor to best-practicesBest practices

  • Use for inline search and filtering: Choose SearchField for filtering within specific sections or lists, not for global navigation or complex multi-step searches.
  • Follow placeholder pattern: Use "Search {items}" format like "Search products" or "Search customers" to clarify scope.
  • Choose the right event: Use input for real-time filtering as users type. Use change for expensive operations that should wait until typing completes.
  • Handle empty values: When the field is cleared, reset filters or show all items appropriately.
Was this page helpful?