---
title: Design considerations for commerce wrapper pages
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

## Design considerations for listing pages

### Consider how products will be filtered

Will you use [taxonomy tags](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/model-taxonomies.md), [content type fields](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md), [price ranges](https://docs.kentico.com/modules/commerce-content-modeling/model-price-options-for-variants.md#model-price-options-for-variants), or a combination? Decide whether editors need to override the automatic order or if products should always sort by date, popularity, or price. Determine whether featured products should appear first in each listing.

The following product listing allows editors to hand-pick products to display. Using widget [personalization](https://docs.kentico.com/documentation/developers-and-admins/digital-marketing-setup/content-personalization.md), they can easily tailor selected products to different audiences.

![Product listing widget on Kbank demo site](https://docs.kentico.com/docsassets/modules/design-considerations-for-commerce-wrapper-pages/kbank_product_listing_widget_manual_selection.png "Product listing widget on Kbank demo site")

> **Info:** **Pattern takeaway:** Combine manual selection with personalization to tailor product visibility for different audience segments.

### Plan for listing edge cases

How will you handle empty listing pages when no products match the criteria? Will you show a _No products found_ message, display featured products as a fallback, or automatically redirect to a dedicated page?

### Choose a filtering approach

When modeling a listing page, decide which **filtering strategy** your product listings will use. Although the visitor-facing experience may look similar, the underlying implementation differs significantly and affects your content model.

**Search index-based filtering** uses a search engine (such as [Lucene or Azure AI Search](https://docs.kentico.com/documentation/developers-and-admins/third-party-integrations.md) integration) to filter products by facets included in the search index. With this approach, the search engine handles filtering logic, supports full-text search alongside faceted navigation, and performs well with large catalogs. However, you need to maintain a _search index_ that stays synchronized with your content, and your _filterable attributes must be explicitly mapped_ to the index. This approach is best suited for catalogs where visitors need to combine multiple filter criteria, such as _price_, _category_, _rating_, and _availability_, or when full-text search is a requirement.

**Direct content filtering** queries content items or pages directly based on their content type _field values_, _taxonomy_ assignments, or _content tree position_. This approach requires no additional infrastructure beyond your Xperience instance and gives you real-time access to the latest published content without index synchronization delays. However, _complex multi-facet filtering_ can become resource-intensive on large catalogs, and you may need to carefully optimize queries.

| Consideration             | Search index-based                        | Direct content filtering              |
| ------------------------- | ----------------------------------------- | ------------------------------------- |
| **Content freshness**     | Might be affected by index rebuild timing | Immediately after publishing          |
| **Performance at scale**  | Optimized for large catalogs              | Best for smaller to mid-size catalogs |
| **Infrastructure**        | Requires a search index                   | No additional setup                   |
| **Multi-facet filtering** | Handles complex combinations efficiently  | Can become costly with many facets    |

Your filtering strategy influences your content model. For **search index-based filtering**, ensure the product fields you want to filter by are structured and indexable (avoid storing filterable attributes in rich text fields). For **direct content filtering**, consider using [taxonomy tags](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide/model-taxonomies.md), dedicated classification fields in a content type, or dedicated _categorization_ content types that support efficient querying.

Also consider whether you'll use _pagination_, infinite scroll, or _Load more_ buttons for long product lists. These decisions influence which _template properties_, custom _Page Builder_ widgets, or dedicated _fields_ on the _Content tab_ your listing pages will require.

The following image comes from the Khealth demo site which has since been retired and is no longer publicly available. It shows a location page where users can filter locations based on their preferences.

![Legacy Khealth demo - Location filtering](https://docs.kentico.com/docsassets/modules/design-considerations-for-commerce-wrapper-pages/khealth_demo_site_facet_filtering.png "Legacy Khealth demo - Location filtering")

> **Info:** **Pattern takeaway:** Faceted filtering works best when filter dimensions are modeled as structured classification data rather than free text.

This legacy Khealth example implements filtering (and facets) using the content tree structure, where individual items represent filter options for services and locations, as shown in the following image.

![Legacy Khealth filtering based on the content tree](https://docs.kentico.com/docsassets/modules/design-considerations-for-commerce-wrapper-pages/khealth_demo_site_facets_in_content_tree.png "Legacy Khealth filtering based on the content tree")

> **Info:** **Pattern takeaway:** Content tree-driven facets are viable when you model filter options as content items.