---
title: Model a product detail page
---

> 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 Product listing pages

**Product listing pages** display collections of products. You use them for category pages (like _Business Banking Products_ or _Dog Accessories_), search results or filtered views, and department-level pages like _All Products_. Your listing pages can include [Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder.md) zones to let editors personalize which products appear for different audience segments.

You have two approaches for building product listings. **Approach A** uses query-based listings either through [page template presets](https://docs.kentico.com/documentation/business-users/website-content/page-templates.md#manage-preset-page-templates) with preconfigured widgets (recommended for most scenarios) or list content without the _Page Builder_. **Approach B** uses manual selection (recommended for curated collections).

### Query-based listings (Approach A)

In a **query-based listing**, your listing page does not directly reference individual products. Instead, editors configure filters and criteria, and products are dynamically retrieved based on [taxonomy](https://docs.kentico.com/documentation/developers-and-admins/configuration/taxonomies.md) assignment, _tags_, dedicated _classification_ content types, or [smart folder criteria](https://docs.kentico.com/documentation/business-users/content-hub/content-hub-folders.md#smart-folders) in the _Content hub_.

This approach has clear benefits. Product listings automatically update when editors add new products that match the criteria. Your model reduces editorial maintenance by eliminating the need for editors to manually add products to every relevant listing. The approach scales well for large product catalogs.

For example, a _Business Banking Products_ page configured to filter by the _Business Banking_ taxonomy will automatically show all current and future products tagged with that category.

#### Use Page Builder with page template presets

We recommend using [Page Builder](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder.md) to present product listings. This approach provides editors with the most flexibility and the best editing experience. Create a **Product Listing Page** content type with minimal structural fields, then use [page template presets](https://docs.kentico.com/documentation/business-users/website-content/page-templates.md#manage-preset-page-templates) to automatically populate preconfigured widgets when editors create new listing pages.

Your **Product Listing Page** content type can include:

- **Core content schema** (or create individual fields) for the page's _title_, _description_, and _thumbnail_
- **Configuration for filtering criteria**, such as a [taxonomy selector](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md#add-option-to-tag-content) to specify which categories or subcategories to display, tag filters to include or exclude specific tags, and content type filters if you want to show only certain product types.
- **Channel-specific metadata:** _SEO metadata schema_, _Open Graph metadata_, _hero_ or _banner content_ specific to this listing page.

> **Info:** _Pagination settings_ (such as number of products per page), _default sort order_ options, and other similar properties aren't product data. They define how product data, such as individual products or products from a single category, is presented. We recommend configuring data presentation via [page template properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder/page-template-properties.md) or [widget properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties.md), rather than storing it as part of the product data within the _Product Listing Page_ content type.

**Decide where editors will control presentation settings**

Editors can configure presentation options at the **template level** through [template properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder/page-template-properties.md) (affecting the entire page) or at the **widget level** through [widget properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties.md) (providing more granular control per widget instance). Template-level properties work well for consistent page-wide settings, such as default sort order or the number of columns, while widget-level properties give editors the flexibility to vary presentation within the same page.

Create _product listing widgets_ that read the filter criteria from your **Product Listing Page** content type and dynamically retrieve matching products. Expose key presentation options, such as _display style_ and _sort order_, through your chosen properties approach. Use [section properties](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/sections-for-page-builder/section-properties.md) to let editors adjust page layout elements like column count without requiring code changes if they prefer a more granular approach.

For inspiration, you can check the _Articles_ widget on the Kbank demo site. Editors can define subpages within a specific section of the Content tree and then further filter the selected content by tags or by specifying how many articles to include. Your _product listing widgets_ can work similarly.

![Kbank article widget properties](https://docs.kentico.com/docsassets/modules/model-product-detail-page/kbank_article_widget_properties.png "Kbank article widget properties")

> **Info:** **Pattern takeaway:** Use widget and template properties to control listing presentation without changing the underlying product model.

When editors create a new listing page, assign an existing [page template preset](https://docs.kentico.com/documentation/business-users/website-content/page-templates.md#manage-preset-page-templates) to automatically populate preconfigured widgets. This automation works particularly well when you create products and listing pages over [API](https://docs.kentico.com/api/content-management/pages.md).

This approach supports [widget personalization](https://docs.kentico.com/guides/digital-marketing/xperience-essentials/personalize-website-content-essentials.md) for different audience segments, allows editors to customize page layout without developer involvement, and provides the most intuitive editing experience.

> **Tip:** If you don't like the custom _Page Builder_ widgets, you might want to consider adding fields on the page's _Content_ tab where editors configure the listing.

#### Embrace developer-driven page rendering

If you decide to implement product listings programmatically with developers controlling the _presentation layer_ directly (rendering product data without _Page Builder_ widgets), you should still include _Page Builder_ capabilities for content personalization.

At minimum, add a [Page Builder editable area](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder.md#page-builder-components) through your page template properties. This allows editors to add supplementary content sections, such as:

- Personalized _Featured products_ widgets for different audience segments
- Promotional banners or callouts specific to certain visitor types
- Cross-sell or related product sections
- Marketing content that complements the programmatic product listing

This hybrid approach gives developers full control over the core product listing logic while preserving editorial flexibility for personalization and promotional content.

### Manual selection listings (Approach B)

In a **manual selection listing**, the product listing page directly references specific products using _widgets_ or a _content item selector_ configured to allow multiple product selections. Editors manually curate which products appear and control their order by dragging items in the selector.

This approach works well when _editorial curation is important_, especially for featured or curated collections, seasonal promotions that highlight specific products, or any scenario where you need full control over which products appear and in what order.

You can create a **Universal page** (or a dedicated **Product listing page**) content type with the same channel-specific metadata as above: SEO metadata schema, Open Graph metadata, and page-specific hero or banner content. Then define a product listing _page template_ with properties, allowed _sections_, and _Product widgets_ that editors can use to display product data on the website.

The following image shows how you can compare products that share the same modular Featured content properties. Editors select which products to compare, and developers ensure the data is properly displayed. You can use this approach to replace traditional comparisons, which were commonly defined through product comparison tables, meaning the data and features were often stored (and duplicated) within individual products.

![Product comparator widget on Kbank](https://docs.kentico.com/docsassets/modules/model-product-detail-page/kbank_product_comparator_widget.png "Product comparator widget on Kbank")

> **Info:** **Pattern takeaway:** Use manual selection when editorial curation and ordering matter more than automatic, catalog-driven updates.

Optionally, you can create a product listing page with a **Product selection** field. Besides SEO and other fields, it will include a _content item selector_ configured for multiple products, allowing editors to manually reorder selections on the Content tab, rather than using Page Builder widgets.

The following image shows the _Dancing Goat_ website, where editors use the _Event_ field to select events to be promoted on the Home page. The events can then be displayed on the website. In the Dancing Goat website’s case, only the first item is displayed. In real life, selected _events_ (or _products_ in your model) can be displayed through a slideshow widget, or dynamically without the editor’s intervention, based on a configuration prepared by the developers.

![Dancing Goat Event selector on Home page](https://docs.kentico.com/docsassets/modules/model-product-detail-page/dancing_goat_event_selector.png "Dancing Goat Event selector on Home page")

> **Info:** **Pattern takeaway:** Multi-select references on listing pages are effective for curated campaigns and limited spotlight collections.

> **Tip:** Choose **query-based listings** for **large catalogs** that need automatic updates. Choose **manual selection** for curated collections where editors need **control over product order, selection, and content personalization**.