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

# shopify:collection:update

Fires when a buyer changes a filter or the sort order on a collection.

You can use this to see how buyers narrow a collection, which filters they use, and how many products they end up with. Merchandising apps use the same signal to reorder or promote products as the list changes.

The event carries the filters and sort order the buyer chose, along with the collection's own `productsCount` before any filtering. The promise resolves with a second `productsCount`, the number that matched, once the storefront has run the query.

You dispatch it from the collection's filter form. `productFilters` is present whenever filters are active and omitted when there are none, and `sortKey` carries the current sort order. A failed update [rejects the promise](https://shopify.dev/docs/api/storefront-events-and-actions/events/listen#waiting-for-the-result).

#### Properties

* **collection**

  **StandardEventCollection**

  **required**

  The collection being filtered or sorted.

* **promise**

  **Promise\<CollectionUpdateResult>**

  **required**

  Resolves once the storefront knows how many products matched.

* **product​Filters**

  **ProductFilter\[]**

  The filters now applied. Omitted when no filters are active.

* **sort​Key**

  **'BEST\_SELLING' | 'COLLECTION\_DEFAULT' | 'CREATED' | 'ID' | 'MANUAL' | 'PRICE' | 'RELEVANCE' | 'TITLE'**

  The sort order now applied. Omitted when no sort order is selected.

* **detail**

  **Record\<string, unknown>**

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

### StandardEventCollection

A collection on the storefront.

* id

  The collection GID. This is \`null\` for built-in collections with no collection record, such as the all-products collection.

  ```ts
  string | null
  ```

* handle

  The collection handle, such as \`summer-sale\`.

  ```ts
  string
  ```

* productsCount

  How many products the collection currently contains.

  ```ts
  number
  ```

### 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 }
  ```

### CollectionUpdateResult

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

* productsCount

  How many products matched the filters and sort order.

  ```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 { CollectionUpdateEvent } from '@shopify/standard-events';

  const deferred = CollectionUpdateEvent.createPromise();

  element.dispatchEvent(
    new CollectionUpdateEvent({
      collection: { id: collectionId, handle, productsCount },
      productFilters: [{ available: true }, { productVendor: 'Acme' }],
      promise: deferred.promise,
    }),
  );

  const results = await fetchFilteredProducts(filters);

  deferred.resolve({ productsCount: results.length });
  ```

* ####

  ##### Listen for the event

  ```javascript
  document.addEventListener('shopify:collection:update', (event) => {
    event.promise.then(({ productsCount }) => {
      if (productsCount === 0) {
        suggestBroaderFilters(event.collection.handle);
      }
    });
  });
  ```

***