---
title: Understand the three widget patterns
---

> 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).

## Understand the three widget patterns

When designing widgets, your most important decision is how each widget sources its content. Xperience supports three distinct patterns, each with different trade-offs in terms of reusability and content governance.

### Pattern A: Overwrite default content in widget properties

_Mixed content widgets_ reference a content item from the _Content hub_ **and** provide override properties that let editors customize specific fields without modifying the original content. This is the recommended pattern for most commerce widgets because it gives marketers the flexibility to optimize their content and messaging, campaign variations, and audience segmentation while keeping the core product or pet data intact.

**Example:** A _ProductCardWidget_ can reference a _Premium Dog Food 25lb_ product from the _Content hub_. On a campaign page, the editor overrides the headline to _Summer Special: Premium Dog Food_ and adds a _20% Off_ promotional badge - without changing the original product data. The following image shows the same scenario with a different product - a _Car loan_ in the Kbank demo site.

![Customized product widget from Kbank demo site](https://docs.kentico.com/docsassets/modules/understand-three-widget-patterns/kbank_customized_product_widget.png "Customized product widget from Kbank demo site")

Editors use the _product widget_ to select a product to display. They can override the default values for product title, description, and image. They can also adjust which product data is displayed in the widget, such as product features.

### Pattern B: Reference content in widgets

_Referenced content_ widgets display content exactly as it's stored in the _Content hub_, with no override capabilities. Use this pattern when data integrity is the priority, and you need consistent, canonical content display.

**Example:** An _ImageWidget_ displays a product photograph exactly as stored, with the same aspect ratio, alt text, and caption everywhere it appears. Similarly, the _Products_ widget on the Dancing Goat website displays only reusable product data, and editors have no way to override these default values, as you can see in the following picture.

![Product listing on the Dancing goat website](https://docs.kentico.com/docsassets/modules/understand-three-widget-patterns/dancing_goat_product_cards.png "Product listing on the Dancing goat website")

### Pattern C: Store content in widgets

_Stored content_ widgets don't reference _Content hub_ data (except for images and similar assets). The data lives directly on the page within the widget configuration, which ties the content to a specific page URL and makes the content almost impossible to reuse in other channels. Use this pattern for truly one-off content that exists only on a specific page.

**Example:** A _Rich Text Widget_ provides a unique introduction paragraph for a campaign landing page – content that won't be reused anywhere else.

![Rich text widget on one of the Kbank's account pages](https://docs.kentico.com/docsassets/modules/understand-three-widget-patterns/kbank_rich_text_widget.png "Rich text widget on one of the Kbank's account pages")

**When to pick each pattern**







For more about how Xperience handles widget data storage and the implications for content reuse, see [the differences between structured content and Page Builder content](https://docs.kentico.com/guides/architecture/content-modeling/xperience-content-modeling-basics/differences-between-structured-content-and-page-builder-content.md).

Now that you understand the three patterns, let's explore how to design each type, starting with the most flexible widgets, which allow editors to adapt the reusable content.