Sana Assistant (online)
Table of Contents

Facet presentations (ADK)

This article provides reference material for the Web store ADK facets shared module.

The module lets add-ons register custom facet presentations that replace the built-in list and range facet UI on product list and search pages. Each presentation is paired with a server-side extension class. See ProductListFacetDisplayExtension and ProductRangeFacetDisplayExtension.

Note

This feature is client-side only for rendering. Server-side extension classes are required so Sana Admin can list available presentations and persist the admin user's choice.

Prerequisites

  • Read Sana ADK and JavaScript APIs for how Web store vs Admin APIs are separated and how sana/<module> imports work.
  • Implement the matching server-side extension class before exporting display components.

Module import

Add-ons import facet display component types from the Web store ADK shared module:

import type {
  FacetListDisplay,
  FacetListModalDisplay,
  FacetRangeDisplay,
  FacetRangeModalDisplay,
  AddonFacets,
} from 'sana/facets';

Addon export

The facets object is an optional property on the add-on AddonExports object. Keys under list and range must match the Type property of the corresponding server-side extension class.

import type { AddonExports } from 'sana/types';
import ChipListFacetDisplay from 'components/facetDisplays/ChipListFacetDisplay';
import ChipListFacetModalDisplay from 'components/facetDisplays/ChipListFacetModalDisplay';
import SliderRangeFacetDisplay from 'components/facetDisplays/SliderRangeFacetDisplay';
import SliderRangeFacetModalDisplay from 'components/facetDisplays/SliderRangeFacetModalDisplay';

const addonExports: AddonExports = {
  facets: {
    list: {
      ChipList: {
        display: ChipListFacetDisplay,
        modalDisplay: ChipListFacetModalDisplay,
      },
    },
    range: {
      SliderRange: {
        display: SliderRangeFacetDisplay,
        modalDisplay: SliderRangeFacetModalDisplay,
      },
    },
  },
};

export default addonExports;

AddonFacets type

Property Type Description
list Record<string, AddonListFacet> Custom list facet presentations keyed by display type name.
range Record<string, AddonRangeFacet> Custom range facet presentations keyed by display type name.

Each AddonListFacet and AddonRangeFacet entry provides:

Property Type Description
display FacetListDisplay or FacetRangeDisplay Inline facet UI on desktop and mobile product list/search pages.
modalDisplay FacetListModalDisplay or FacetRangeModalDisplay Facet UI inside the mobile facets modal, where selection is staged locally before applying.

List facet display components

FacetListDisplay

Renders a custom list facet on the product list or search page.

Property Type Description
id string Unique HTML element identifier prefix for the facet.
facet ListFacet Metadata of the list facet being rendered.
values ListFacetValue[] The facet values currently available for display.
valuesTotalCount number Total number of facet values, including values not yet loaded.
topValuesCount number Number of top facet values initially shown before loading the rest.
loadAllValues () => void Loads all remaining facet values when only a subset is initially available.

ListFacet

Property Type Description
name string The facet name.
multiSelect boolean Indicates whether multiple values can be selected.
fieldType string \| null The facet field type.

ListFacetValue

Property Type Description
value string \| null The facet value identifier.
title string The display title of the facet value.
textTitle string \| null The text title of the facet value.
count number The number of products matching this facet value.
selected boolean Whether this facet value is currently selected.
link Link The facet navigation link. Use with the Link component from sana/elements to apply the filter.

FacetListModalDisplay

Renders a custom list facet in the mobile facets modal. Selection is staged locally; the page filter updates when the shopper applies the modal.

Property Type Description
id string Unique HTML element identifier prefix for the facet.
facet ListFacet Metadata of the list facet being rendered.
values ModalListFacetValue[] Facet values available in the modal (same as ListFacetValue without link).
valuesTotalCount number Total number of facet values, including values not yet loaded.
topValuesCount number Number of top facet values initially shown before loading the rest.
toggleValue (value: ModalListFacetValue) => void Toggles the selection state of a facet value in the local modal selection.

Range facet display components

FacetRangeDisplay

Renders a custom range facet on the product list or search page.

Property Type Description
id string Unique HTML element identifier prefix for the facet.
facet RangeFacet Metadata of the range facet being rendered.
initialMinValue number The initially selected minimum value.
initialMaxValue number The initially selected maximum value.
getTotalCount (range: Range) => Observable<number> \| void Returns the number of products matching the given range. Use to preview the result count before applying the filter.
onSubmit (range: Range) => void Applies the selected range filter to the page.

RangeFacet

Property Type Description
name string The facet name.
minValue number The minimum available value of the facet.
maxValue number The maximum available value of the facet.
fieldType 'Integer' \| 'BigInteger' \| 'Decimal' \| 'Price' \| null The numeric field type of the facet.

Range

Property Type Description
minValue number The selected minimum value.
maxValue number The selected maximum value.

FacetRangeModalDisplay

Renders a custom range facet in the mobile facets modal.

Property Type Description
id string Unique HTML element identifier prefix for the facet.
facet RangeFacet Metadata of the range facet being rendered.
initialMinValue number The currently selected minimum value in the modal.
initialMaxValue number The currently selected maximum value in the modal.
selectRange (range: Range) => void Updates the locally selected range in the modal.
onSubmit (range: Range) => void Applies the selected range filter to the page.
onRangeChange () => void Invoked when the selected range changes so the modal can reset its apply state.

See also