---
title: SearchField
description: >-
  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.
api_version: 2025-10
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/polaris-web-components/forms/searchfield
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/polaris-web-components/forms/searchfield.md
---

# Search​Field

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.

## Properties

Configure the following properties on the `SearchField` component.

* 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.

* id

  string

  A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features.

* placeholder

  string

  A short hint that provides guidance about the expected value of the field.

* value

  string

  The current search query text entered in the field. An empty string means no search query is entered.

## Events

The `SearchField` component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events).

* blur

  (event: CallbackEvent<"s-search-field">) => void

  Called when the element loses focus.

* change

  (event: CallbackEvent<"s-search-field">) => void

  Called after editing completes, typically on blur.

* focus

  (event: CallbackEvent<"s-search-field">) => void

  Called when the element receives focus.

* input

  (event: CallbackEvent<"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.

  ```ts
  boolean
  ```

* cancelable

  Whether the event can be canceled.

  ```ts
  boolean
  ```

* composed

  Whether the event will trigger listeners outside of a shadow root.

  ```ts
  boolean
  ```

* currentTarget

  The element that the event listener is attached to.

  ```ts
  HTMLElementTagNameMap[T]
  ```

* detail

  Additional data associated with the event.

  ```ts
  any
  ```

* eventPhase

  The current phase of the event flow.

  ```ts
  number
  ```

* target

  The element that triggered the event.

  ```ts
  HTMLElementTagNameMap[T] | null
  ```

```ts
interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
  /**
   * The element that the event listener is attached to.
   */
  currentTarget: HTMLElementTagNameMap[T];
  /**
   * Whether the event bubbles up through the DOM tree.
   */
  bubbles?: boolean;
  /**
   * Whether the event can be canceled.
   */
  cancelable?: boolean;
  /**
   * Whether the event will trigger listeners outside of a shadow root.
   */
  composed?: boolean;
  /**
   * Additional data associated with the event.
   */
  detail?: any;
  /**
   * The current phase of the event flow.
   */
  eventPhase: number;
  /**
   * The element that triggered the event.
   */
  target: HTMLElementTagNameMap[T] | null;
}
```

### Examples

* #### Enable search with a search field

  ##### Description

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

  ##### Default

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

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/pos-ui-extensions/2025-10/search-field-default.png)

## Best 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.

## Examples

Learn how to handle search input and implement real-time filtering.

### Examples

* #### Handle search input events

  ##### Description

  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.

  ##### Default

  ```jsx
  <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')}
  />
  ```