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.

Anchor to propertiesProperties

Anchor to collection collection required: The collection being filtered or sorted.
Anchor to promise promise Promise<> required: Resolves once the storefront knows how many products matched.
Anchor to productFilters productFilters []: The filters now applied. Omitted when no filters are active.
Anchor to sortKey sortKey 'BEST_SELLING' | 'COLLECTION_DEFAULT' | 'CREATED' | 'ID' | 'MANUAL' | 'PRICE' | 'RELEVANCE' | 'TITLE': The sort order now applied. Omitted when no sort order is selected.
Anchor to detail 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.
```
string | null
```
handle
The collection handle, such as `summer-sale`.
```
string
```
productsCount
How many products the collection currently contains.
```
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.
```
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 }
```

CollectionUpdateResult

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

productsCount
How many products matched the filters and sort order.
```
number
```
detail
Optional custom data for the storefront's internal use. Listeners can read it.
```
Record<string, unknown>
```

Examples

Dispatch the event

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

Examples

Dispatch the event

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

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

Was this page helpful?