Skip to main content

Facets & Filters

Facets are the primary mechanism for attaching structured, queryable metadata to your catalog. A Facet represents a label category — such as "Brand", "Material", or "Season" — and contains one or more FacetValues representing specific entries within that category, like "Nike", "Cotton", or "Summer 2025".

Facets and FacetValues

The relationship is straightforward:

  • A Facet is a named grouping (e.g., "Color").
  • A FacetValue is a specific value within that grouping (e.g., "Red", "Blue", "Green").

FacetValues can be assigned to Products or ProductVariants. Assigning at the product level applies the value to all of that product's variants. Assigning at the variant level allows more granular control — for instance, tagging only certain color variants with a "Limited Edition" value.

Three primary use cases

Facets serve three distinct purposes in Vendure, all built on the same underlying data model:

1. Collection basis

Collections can be configured to automatically include products based on facet value membership. For example, a "Running Shoes" collection might include all products tagged with the "Running" value from the "Category" facet. When new products receive that facet value, they are automatically added to the collection.

When customers browse a collection or search the catalog, facet values power the familiar "filter by" sidebar. The search system returns facet value aggregations — counts of how many results match each facet value — so your storefront can display dynamic filter options like "Brand: Nike (12), Adidas (8)" and let customers narrow their results.

Filters within the same facet are typically combined with OR logic (show Nike or Adidas), while filters across different facets use AND logic (show Nike and size Large).

3. Internal logic

Facets are not limited to customer-facing features. You can use them to drive backend behavior:

  • A promotion that applies a 20% discount to all variants tagged with "Clearance".
  • A shipping rule that adds a surcharge for products tagged with "Oversized" or "Fragile".
  • Business reporting that groups sales by "Product Line" or "Supplier".

Public vs. private facets

Each facet has a isPrivate flag. When set to true, the facet and its values are hidden from the Shop API and will not appear in storefront search results or filter menus. Private facets are only visible in the Admin API.

This is useful for facets that drive internal logic — like a "Warehouse Location" or "Margin Tier" facet — that should not be exposed to customers.

Facet values and custom fields

Like most Vendure entities, both Facets and FacetValues support custom fields. This allows you to attach additional data to facet values — for example, a hex color code on "Color" facet values for rendering color swatches in your storefront, or an icon identifier for category facets.

Channel awareness

Facets and FacetValues are channel-aware. In a multi-channel setup, you can control which facets are available in each channel. A facet created in one channel will also be visible in the default channel, but not necessarily in other sub-channels unless explicitly assigned.

This means you can have channel-specific facets — for instance, a "Region Exclusive" facet that only exists in certain regional channels — while still sharing common facets like "Brand" across all channels.

  • Products — How facet values are assigned to products and variants
  • Collections — Using facet values as the basis for dynamic collections
  • Search — Facet value aggregations in search results
  • Promotions — Using facet values to target promotion conditions and actions
Was this chapter helpful?
Report Issue
Edited Feb 12, 2026·Edit this page