About custom facet presentations

Starting with Sana Commerce Cloud 1.148, add-ons can register custom facet presentations for product list and search pages.

In addition to the built-in presentations — a list of values (regular or searchable) and a range input — add-ons can provide their own UI for how facet values are rendered and interacted with. Admin users assign a presentation per facet in the product search index configuration.

Common scenarios include:

• Rendering facet values as color swatches or chips instead of a plain text list.
• Providing a slider or other custom control for range facets.
• Applying a hidden presentation that keeps a facet fully functional in page data while rendering no UI at all (including its header), useful when a facet must remain present in the page configuration but should not be visible on the storefront.

How it works

Custom facet presentations require both a server-side extension and client-side display components:

1. Server-side — Implement ProductListFacetDisplayExtension or ProductRangeFacetDisplayExtension to register the presentation with a unique Type and admin-visible Title.
2. Client-side — Export matching display and modalDisplay React components from the add-on's webstore entry module under facets.list or facets.range, keyed by the same Type value.
3. Sana Admin — An admin user selects the custom presentation when configuring a facet on the product search index or product list page.

The Type value must match across the server extension, client export, and admin configuration. Sana resolves the presentation at runtime based on the packageId and type stored for each facet.

Guides

• Implementing a custom facet presentation

Reference

• ProductListFacetDisplayExtension reference
• ProductRangeFacetDisplayExtension reference
• Facet presentations (ADK)
• ProductSearchFacetDisplayType reference