Choose a version:

Search field

The search field 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 (9)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the SearchField component.

Anchor to disabled disabled boolean Default: false: Whether the field is disabled, preventing user interaction. Use when the field is temporarily unavailable due to application state, permissions, or dependencies.
Anchor to id id string: A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features.
Anchor to placeholder placeholder string: A short hint that provides guidance about the expected value of the field.
Anchor to value value string: The current search query text entered in the field. An empty string means no search query is entered.

Anchor to EventsEvents

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

Anchor to blur blur (event: <"s-search-field">) => void: Called when the element loses focus.
Anchor to change change (event: <"s-search-field">) => void: Called after editing completes, typically on blur.
Anchor to focus focus (event: <"s-search-field">) => void: Called when the element receives focus.
Anchor to input input (event: <"s-search-field">) => void: Called when the user makes any changes in the field.

CallbackEvent

Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior.

bubbles
Whether the event bubbles up through the DOM tree.
```
boolean
```
cancelable
Whether the event can be canceled.
```
boolean
```
composed
Whether the event will trigger listeners outside of a shadow root.
```
boolean
```
currentTarget
The element that the event listener is attached to.
```
HTMLElementTagNameMap[T]
```
detail
Additional data associated with the event.
```
any
```
eventPhase
The current phase of the event flow.
```
number
```
target
The element that triggered the event.
```
HTMLElementTagNameMap[T] | null
```

Anchor to ExamplesExamples

Anchor to Enable search with a search fieldEnable search with a search field

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

Enable search with a search field

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

Anchor to 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 Best practicesBest practices

Use for inline search and filtering: Choose search field 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?