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.

Anchor to propertiesProperties

Anchor to search search required: The query, filters, and sort order the buyer submitted.
Anchor to promise promise Promise<> required: Resolves once the storefront knows how many results matched.
Anchor to detail 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.
```
string
```
productFilters
The filters applied to the results.
```
ProductFilter[]
```
sortKey
The sort order applied to the results.
```
'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.
```
boolean
```
category
Filters on a taxonomy category ID.
```
{ id: string }
```
price
Filters on a price range.
```
{ min?: number, max?: number }
```

productMetafield

Filters on a product metafield.

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

productType
Filters on the product type.
```
string
```
productVendor
Filters on the product vendor.
```
string
```
tag
Filters on a product tag.
```
string
```
taxonomyMetafield
Filters on a taxonomy metafield.
```
{ key: string, value: string }
```

variantMetafield

Filters on a variant metafield.

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

variantOption
Filters on a variant option, such as a color.
```
{ name: string, value?: string }
```

SearchUpdateResult

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

totalCount
How many results matched.
```
number
```
detail
Optional custom data for the storefront's internal use. Listeners can read it.
```
Record<string, unknown>
```

Examples

Dispatch the event

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 });

Examples

Dispatch the event

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

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

Was this page helpful?