Collection Filters Extension

The Collection Filters Extension lets you change collection filters before products are fetched. It also runs again whenever the user changes the selected filters. Use this extension when you want to:

Preselect filters before products load.
Add or remove selected filter values.
Set or clear a price range.
Set or clear the product order.
Hide or show filters.
React when the user changes filters.

Exported Function

Your project must export a function named prepareCollectionProductsFilters.

export async function prepareCollectionProductsFilters(
  context: CollectionProductsFiltersContext
) {
  // Edit filters here.
}

The function can be synchronous or asynchronous. If the function returns a promise the app will wait up to 3 seconds before assuming the extension failed.

When It Runs

The extension receives a trigger that tells you why it is running.

type CollectionProductsFiltersTrigger = "Initial" | "UserFiltersChanged";

The triggers are:

Initial: runs before the application fetches products for the collection.
UserFiltersChanged: runs after the user changes filters, before the application fetches the updated products.

Use Initial when you want to apply default filters. Use UserFiltersChanged when you want to react to the user’s current filter selection.

Context

The function receives a context object.

interface CollectionProductsFiltersContext {
  collection: CollectionProductsCollectionInfo;
  trigger: CollectionProductsFiltersTrigger;
  filters: CollectionProductsFiltersEditor;
}

interface CollectionProductsCollectionInfo {
  id: string;
  title: string;
}

Use context.collection to know which collection is being loaded. Use context.trigger to know why the extension is running. Use context.filters to inspect and change the filters.

Filter Editor

The filters editor lets you change the selected filters and the visible filters.

export interface CollectionProductsFiltersEditor {
  available: AvailableCollectionProductsFilters;

  addValueById(filterId: string, value: string): boolean;
  addValueByLabel(filterLabel: string, value: string): boolean;

  removeValueById(filterId: string, value: string): boolean;
  removeValueByLabel(filterLabel: string, value: string): boolean;

  clearById(filterId: string): boolean;
  clearByLabel(filterLabel: string): boolean;

  hasValueById(filterId: string, value: string): boolean;
  hasValueByLabel(filterLabel: string, value: string): boolean;

  setPriceRange(min: number, max: number): void;
  clearPriceRange(): void;

  setOrder(order: FilterOrder): boolean;
  clearOrder(): boolean;

  hideFilterById(filterId: string): boolean;
  hideFilterByLabel(filterLabel: string): boolean;
  showFilterById(filterId: string): boolean;
  showFilterByLabel(filterLabel: string): boolean;
  isFilterHiddenById(filterId: string): boolean;
  isFilterHiddenByLabel(filterLabel: string): boolean;
}

Methods that return boolean return true when the change was applied.

Available Filters

You can inspect the filters that are available for the collection.

interface AvailableCollectionProductsFilters {
  readonly all: AvailableCollectionProductsFilter[];

  findById(id: string): AvailableCollectionProductsFilter | null;
  findByLabel(label: string): AvailableCollectionProductsFilter | null;
}

interface AvailableCollectionProductsFilter {
  readonly id: string;
  readonly label: string;
  readonly type: FilterType;
  readonly isExtra: boolean;
  readonly values: AvailableCollectionProductsFilterValue[];

  hasValue(value: string): boolean;
}

interface AvailableCollectionProductsFilterValue {
  readonly label: string;
  readonly value: string;
  readonly count: number | null;
  readonly isVariantOptionFilter: boolean;
}

Filter Types

type FilterType =
  | "LIST"
  | "SINGLE_SELECTION_LIST"
  | "ORDERING"
  | "PRICE_RANGE";

Ordering

Use setOrder to change the product ordering.

type FilterOrder =
  | "None"
  | "Ascending"
  | "Descending"
  | "BestSelling"
  | "Relevance"
  | "RecentProducts"
  | "OldestProducts"
  | "NameAscending"
  | "NameDescending"
  | "OldProducts";

Example:

export function prepareCollectionProductsFilters(
  context: CollectionProductsFiltersContext
) {
  if (context.trigger === "Initial") {
    context.filters.setOrder("BestSelling");
  }
}

Example: Add a Default Filter

export function prepareCollectionProductsFilters(
  context: CollectionProductsFiltersContext
) {
  if (context.trigger !== "Initial") {
    return;
  }

  const filter = context.filters.available.findByLabel("Color");

  if (!filter?.hasValue("black")) {
    return;
  }

  context.filters.addValueByLabel("Color", "black");
}

Example: Hide a Filter

export function prepareCollectionProductsFilters(
  context: CollectionProductsFiltersContext
) {
  context.filters.hideFilterById("filter.p.vendor");
}

Example: Set a Price Range

export function prepareCollectionProductsFilters(
  context: CollectionProductsFiltersContext
) {
  if (context.collection.title === "Sale") {
    context.filters.setPriceRange(0, 100);
  }
}

Best Practices

Keep the function fast.
Use Initial for default filter rules.
Use UserFiltersChanged for rules that depend on the user’s current selection.
Prefer filter IDs when you know them.
Check that a filter or value exists before applying it.
Avoid changing filters in a way that surprises the user.

​Exported Function

​When It Runs

​Context

​Filter Editor

​Available Filters

​Filter Types

​Ordering

​Example: Add a Default Filter

​Example: Hide a Filter

​Example: Set a Price Range

​Best Practices