---
title: 'shopify:search:update'
description: Fires when a buyer runs or refines a search.
source_url:
  html: >-
    https://shopify.dev/docs/api/storefront-events-and-actions/events/search-update
  md: >-
    https://shopify.dev/docs/api/storefront-events-and-actions/events/search-update.md
api_name: storefront-events-and-actions
---

# shopify:search:update

Fires when a buyer submits a search, or changes the filters or sort order on results they already have.

You can use this to see what buyers are looking for in their own words, and which searches come back empty. Search and merchandising apps use it to improve results or to surface something else when nothing matched.

The event carries the query, filters, and sort order. The promise resolves with the total number of results, once the storefront has run the search.

You dispatch it from the search's filter form. `query` carries the current search term and persists when the buyer changes only the filters. A failed search [rejects the promise](https://shopify.dev/docs/api/storefront-events-and-actions/events/listen#waiting-for-the-result).

#### Properties

* **search**

  **SearchQuery**

  **required**

  The query, filters, and sort order the buyer submitted.

* **promise**

  **Promise\<SearchUpdateResult>**

  **required**

  Resolves once the storefront knows how many results matched.

* **detail**

  **Record\<string, unknown>**

  Optional custom data for the storefront's internal use. Listeners can read it.

### SearchQuery

A storefront search request.

* query

  The search term the buyer typed.

  ```ts
  string
  ```

* productFilters

  The filters applied to the results.

  ```ts
  ProductFilter[]
  ```

* sortKey

  The sort order applied to the results.

  ```ts
  'RELEVANCE' | 'PRICE'
  ```

### ProductFilter

A filter applied to a product list. Each filter sets exactly one field, and the shape matches the Storefront API \[\`ProductFilter\`]\(/docs/api/storefront/latest/input-objects/ProductFilter) input.

* available

  Filters on whether the product is in stock.

  ```ts
  boolean
  ```

* category

  Filters on a taxonomy category ID.

  ```ts
  { id: string }
  ```

* price

  Filters on a price range.

  ```ts
  { min?: number, max?: number }
  ```

* productMetafield

  Filters on a product metafield.

  ```ts
  { namespace: string, key: string, value?: string }
  ```

* productType

  Filters on the product type.

  ```ts
  string
  ```

* productVendor

  Filters on the product vendor.

  ```ts
  string
  ```

* tag

  Filters on a product tag.

  ```ts
  string
  ```

* taxonomyMetafield

  Filters on a taxonomy metafield.

  ```ts
  { key: string, value: string }
  ```

* variantMetafield

  Filters on a variant metafield.

  ```ts
  { namespace: string, key: string, value?: string }
  ```

* variantOption

  Filters on a variant option, such as a color.

  ```ts
  { name: string, value?: string }
  ```

### SearchUpdateResult

The value a \`shopify:search:update\` promise resolves with.

* totalCount

  How many results matched.

  ```ts
  number
  ```

* detail

  Optional custom data for the storefront's internal use. Listeners can read it.

  ```ts
  Record<string, unknown>
  ```

Examples

### Examples

* ####

  ##### Dispatch the event

  ```javascript
  import { SearchUpdateEvent } from '@shopify/standard-events';

  const deferred = SearchUpdateEvent.createPromise();

  element.dispatchEvent(
    new SearchUpdateEvent({
      search: {
        query: input.value,
        sortKey: 'RELEVANCE',
      },
      promise: deferred.promise,
    }),
  );

  const results = await runSearch(input.value);

  deferred.resolve({ totalCount: results.totalCount });
  ```

* ####

  ##### Listen for the event

  ```javascript
  document.addEventListener('shopify:search:update', (event) => {
    event.promise.then(({ totalCount }) => {
      if (totalCount === 0) {
        recordEmptySearch(event.search.query);
      }
    });
  });
  ```

***