Skip to main content
Facets help shoppers narrow down results quickly by what matters most, like size, color, brand, or price. With Layers, you decide which attributes become filters and how those filters appear to customers. Group values into friendly buckets, control the order so the most helpful options show up first, and hide specific values from customers when needed.
Facet grouping, sorting, and hiding are new features. Please contact support if you encounter any issues.

​
What do you want to do?

​
Where filters come from

Layers is the source of truth for filters on any surface it powers. Which storefront filter UI you use depends on how your theme is wired up:
  • Themes rendered through Layers (SDK, Liquid, or App Embed) — filters are driven by the Facets API and reflect facets configured in the Layers dashboard. Values, counts, and numeric ranges come from Layers, not from Shopify. See Rendering facets with the SDK or Rendering facets in Liquid.
  • Themes that use Shopify’s native storefront filtering — Layers syncs each filterable attribute to Shopify as a facet metaobject when you turn on Enable as Storefront Facet on the attribute. That makes Layers-managed facets selectable in the theme editor’s native filter picker. See Enable as storefront facet and Facet metaobjects.

​
Shopify’s Search & Discovery app

Shopify’s Search & Discovery app configures filters, synonyms, and boosts against Shopify’s native search index. Layers ships its own search and merchandising engine and does not read from the Search & Discovery app’s configuration:
  • Filters — configure filterable attributes in Layers, not in Search & Discovery. On any page powered by Layers (SDK, Liquid, or App Embed), only the Layers facet configuration is applied. Pages that Layers doesn’t power can still use Shopify’s native filtering, and Layers-managed facets appear there via the synced facet metaobjects.
  • Synonyms and typo tolerance — use Layers’ built-in query expansion and typo tolerance instead. Synonyms configured in Search & Discovery are not read by Layers.
  • Product boosts and pins — use Layers merchandising rules and soft boost expressions.
Running the Search & Discovery app alongside Layers is supported — the two do not conflict — but any filter, synonym, or boost you want reflected on Layers-powered surfaces must be configured in Layers.

​
When a facet goes live

Enabling an attribute as a facet queues a build that prepares the facet’s values. The Facets API withholds a facet until its values are ready, so a newly enabled facet does not appear in API responses immediately after you save. The dashboard shows where each facet is in that process. In the attributes table, the Filter column shows an icon for each attribute:
  • Green check — the facet is live, and the Facets API serves it. Facets appear in API responses as soon as they go live, without waiting for caches to expire.
  • Spinner — Layers is preparing the facet’s values. Hover over the icon to see the build status. The API withholds the facet until the build finishes.
  • Alert icon — the build could not complete, and the API does not serve the facet. Hover over the icon to see what happened. Retry the build from the attribute edit sheet, or contact support if it keeps failing.
  • Red X — the attribute is not enabled as a facet.
The attribute edit sheet shows the same states as a status badge: Publishing filter (with progress), Published, or Filter could not be published. If you keep the editor open after saving, the badge and table icon update in place, and a notification confirms when the facet is live. Disabling a facet removes it from API responses on the next request.

​
Facets with too many distinct values

Layers turns a facet off automatically when its values are too numerous to work as a filter. During the facet build, Layers measures each sales channel’s distinct value count and the average number of products per value. Layers disables the facet when, on any channel, it has:
  • More than 10,000 distinct values, or
  • 1,000 or more distinct values with fewer than 2.5 products per value on average.
Facets that trip these limits are usually product identifiers, such as SKUs, style codes, or SEO titles, rather than browsable groupings. Nearly every value matches a single product, so selecting a value in the filter list is just a slower way to open a product page. When Layers disables a facet this way:
  • The attribute’s Enable as Storefront Facet setting turns off, and the Facets API stops serving the facet.
  • The dashboard shows the status Too many distinct values for the facet, so you can tell Layers turned it off automatically rather than a teammate.
  • The product-search-diagnostics MCP tool reports the facet as dropped with the reason facet_cardinality_exceeded. See Diagnosing search coverage.
Re-enabling the facet queues a new build. If the values still exceed the limits, Layers turns it off again. To filter on this kind of data, use an attribute with coarser values instead. For example, map identifier codes to browsable categories with a computed attribute, then enable that attribute as the facet.

​
Designing great filters

  • Show your most‑used filters near the top (Size, Color, Price).
  • Use groups to reduce long lists (Reds/Blues/Neutrals).
  • Keep value labels human‑friendly (e.g., “Navy” instead of codes).
  • Limit group size so menus stay easy to scan.
  • Periodically prune rarely used values based on customer behavior.

​
Best practices for facet management

  • Prioritize popular filters: Place frequently used filter values at the top of the list
  • Use logical grouping: Group related values together to create a more intuitive browsing experience
  • Limit group size: Keep groups to a reasonable size to avoid overwhelming customers
  • Use clear group names: Select descriptive names that help customers understand what’s in each group
  • Regular maintenance: Periodically review and update your facet organization based on changing inventory and customer behavior

​
Example scenarios

  • Color attribute: Group colors by shade families (Reds, Blues, Neutrals) for easier navigation
  • Brand attribute: Create groups for “Featured Brands”, “Local Brands”, and “International Brands”
  • Size attribute: For clothing, group by size categories (XS-S-M, L-XL-XXL, etc.)

​
See also