Malachyte Portal/Pages

Filtering & Sorting

How to configure filters and sorting for Product Listing Pages

The PLP Engine allows clients to control which product attributes are visible as filters on a PLP, while still leveraging the full attribute set available in the collection's result set.


Filter Configuration

The system derives every possible attribute from the collection's returned products, but only displays attributes that have been enabled in the Portal.

Filter Configuration Page

For each collection, clients can:

  • View every attribute detected from the returned product dataset (e.g., size, color, material, price range, tags, metafields, variant attributes)
  • Toggle attributes on or off for PLP visibility
  • Reorder visible filters (optional)

Tip

The filter system automatically discovers all filterable attributes from the collection. Clients control which ones their shoppers see.


How Filter Discovery Works

Candidate Attribute Discovery

The system extracts all filterable attributes from products in the collection:

Attribute SourceExamples
Product FieldsType, vendor, tags, options
Variant AttributesSize, color, inventory status
MetafieldsCustom product attributes
Derived AttributesPrice range, availability

Attribute Normalization

All attribute keys are normalized with canonical casing and naming to ensure consistent filtering behavior across the catalog.


Whitelist-Based Filtering

The PLP Engine uses a whitelist model for filter visibility:

  • allowed_filter_attributes: string[] is the only persisted source of truth for which filters appear on a collection's PLP.
  • The frontend may only render and submit filters that exist in allowed_filter_attributes for that collection.

Drift Handling

Collections change over time. Attributes may disappear as products are added or removed.

The system automatically reconciles the whitelist:

reconciledAllowed = allowed_filter_attributes.filter(attr => 
  candidateAttributes.includes(attr)
)

This ensures dead filters are automatically removed without manual intervention.


Sorting Options

Sorting remains configurable but standardized across PLPs.

Supported Sort Orders

Sort OptionDescription
RecommendedDefault. The order the Pages strategy ranks products in
Price (Low to High)Ascending price order
Price (High to Low)Descending price order
NewestMost recently added products first
OldestLeast recently added products first
A-ZAlphabetical by product title
Z-AReverse alphabetical

Important

Sorting operates within the collection boundary and does not override pinning or dataset-shaping rules (Hide / Only Show). Pinned products remain in their designated positions regardless of sort order.


Runtime Behavior

At runtime, the PLP Engine:

  1. Derives candidate attributes from the current result set
  2. Renders only attributes in allowed_filter_attributes
  3. Validates filter submissions against the whitelist
  4. Applies filters within the bounds of the collection dataset

This ensures a clean, controlled filtering experience that matches the client's intent.


Best Practices

Choosing Filters

  • Enable high-value attributes that help shoppers narrow their search (size, color, price)
  • Disable low-value attributes that add noise without helping navigation
  • Consider mobile UX — fewer filters often work better on small screens

Filter Ordering

  • Place the most commonly used filters at the top
  • Group related attributes together (e.g., all size variants)
  • Consider the product category — fashion may prioritize color/size, electronics may prioritize specs