Skip to main content
The collection filters extension changes collection filters before products are fetched, and runs again whenever the user changes the selected filters. Use it 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, show, or rename filters and filter values.
  • React when the user changes filters.

Exported function

Export the function from your entry file under the extension’s functionName in napps.config.json. See How App Extensions work. The examples on this page name it prepareCollectionProductsFilters.
The function can be synchronous or asynchronous. If it returns a promise, the app waits up to 3 seconds, then treats the extension as failed.

When it runs

The extension receives a trigger that tells you why it is running.
  • Initial: runs before the app fetches products for the collection. Use it to apply default filters.
  • UserFiltersChanged: runs after the user changes filters, before the app fetches the updated products. Use it for rules that depend on the user’s current selection.

Context

The function receives a context object:
collection identifies the collection being loaded, trigger tells you why the extension is running, and filters lets you inspect and change the filters.

Filter editor

The filters editor lets you change the selected filters and the visible filters.
Hiding a filter removes it from the filters shown to the user, but does not clear its selected values, so they can still apply to the product query. renameFilterById and renameFilterByLabel change a filter’s title. renameValueById and renameValueByLabel change the label of a single value; the underlying value stays the same, so selection still matches. Use the clearFilterRename methods to restore the original title. Methods that return boolean return true when the change was applied, and false when the requested filter or value is not available.

Available filters

Inspect the filters available for the collection through filters.available:

Filter types

Ordering

Use setOrder to change the product order. Values match case-insensitively, but prefer the casing shown here:

Example: add a default filter

Example: hide a filter

Example: rename a filter

Example: set a price range

Best practices

  • Prefer filter IDs over labels when you know them.
  • Check that a filter or value exists before applying it.
  • Avoid overriding a filter the user just selected.