Shopify Custom and Default Filters

Most storefront filters should be configured in Filters & Data and Layout Settings. Use JavaScript custom and default filters only for behavior that cannot be represented as a normal merchant-managed facet.

These hooks must be defined before the Search Results or Product Grid App Block starts.

Default Filters

Use window.Nimstrata.search.defaultFilters for hidden filters that should apply to every search or collection request.

Default filters are not shown in the UI, are not shopper-removable, and are not reflected as normal filter controls. They are a good fit for:

Store, warehouse, or region availability gates
B2B buyer segmentation
Channel-specific product restrictions
Temporary launch constraints that should not appear as shopper filters

window.Nimstrata = window.Nimstrata || {};
window.Nimstrata.search = window.Nimstrata.search || {};

window.Nimstrata.search.defaultFilters = [
  {
    field: 'attributes.available_in_market',
    value: ['GB'],
    type: 'string',
  },
  {
    or: [
      { field: 'attributes.channel', value: ['online'], type: 'string' },
      { field: 'attributes.channel', value: ['both'], type: 'string' },
    ],
  },
];

defaultFilters can also be a sync or async function:

window.Nimstrata.search.defaultFilters = async function () {
  const profile = await window.getCustomerProfile?.();

  return profile?.b2b
    ? [{ field: 'attributes.customer_group', value: ['b2b'], type: 'string' }]
    : [];
};

Collection pages already add their collection constraints through the App Block. Only add a collection ID, tag, or market filter manually during a manual install or when intentionally applying an extra hidden rule.

Custom Filters

Use window.Nimstrata.search.customFilters when shoppers need a visible switch for a filter that is not part of the normal facet list.

The current storefront UI supports displayComponent: 'switch'. Custom switches can render in the toolbar or in the sidebar/filter drawer.

window.Nimstrata = window.Nimstrata || {};
window.Nimstrata.search = window.Nimstrata.search || {};
window.Nimstrata.search.customFilters =
  window.Nimstrata.search.customFilters || [];

window.Nimstrata.search.customFilters.push({
  name: 'in_stock',
  displayName: 'In stock',
  displayComponent: 'switch',
  displayLocation: 'toolbar',
  defaultActive: false,
  filter: {
    field: 'availability',
    value: ['IN_STOCK'],
    type: 'string',
  },
});

Use the nested filter property for new work. Older inline custom filters with field, value, and type still work for backwards compatibility.

Custom Filter Fields

The search App Block only receives facet metadata for fields that are requested as filters. If a custom filter uses a field that is not already in the App Block filter list, add it to window.Nimstrata.search.customFields so the storefront can decide whether the switch is relevant for the current result set.

window.Nimstrata.search.customFields = [
  { field: 'attributes.available_in_store', type: 'number' },
];

Without this, a custom switch may be hidden because the storefront cannot confirm that applying it could return results.

Default Active Custom Filters

Set defaultActive: true when a custom filter should start enabled but still be shopper-removable.

The URL uses cf for custom filters the shopper turns on and cf-off for default-active custom filters the shopper turns off. Use the name as the stable identifier, and avoid changing it once URLs are live.

Search Versus Recommendations

Search and collection pages use window.Nimstrata.search.defaultFilters.

Recommendations use a separate property:

window.Nimstrata = window.Nimstrata || {};
window.Nimstrata.recs = window.Nimstrata.recs || {};
window.Nimstrata.recs.defaultFilters = [
  { field: 'attributes.available_in_market', value: ['GB'], type: 'string' },
];

Recommendations automatically include an in-stock filter unless the configured recommendation filters already include an availability filter, including one nested inside or, and, or not.

When Not To Use These Hooks

Do not use custom or default filters to replace normal filter configuration. If the filter should appear as a normal facet, configure the attribute in App Block Filters. If the filter is only about layout, count display, quick filters, search-within-filters, or sorting placement, use Layout Settings.