> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Diversity expressions in sort orders

> Cap how many products share the same family, product type, or attribute in the top window of a collection so the first page shows a broader assortment.

## What diversity does

A **diversity** expression limits how many products from the same group are allowed in the top **K** positions of a sort order or merchandising rule. Without it, the first page can show six near-duplicates of the same style in a row. With it, more distinct products surface before a customer has to scroll.

Groups are defined by one or more **diversity axes**. An axis can group by [product family](/platform/product-families) or by any categorical attribute — for example, product type, vendor, or color. When you configure multiple axes on the same expression, each axis enforces its own cap independently. A product only enters the top window if it fits under every axis at once.

Diversity acts on the **top window** only. Beyond the window, products fall back to their natural sort order and repeats are allowed again.

<Note>
  When an axis groups by product family, at least one [product family](/platform/product-families) must be configured. Without families, that axis has nothing to group by and will have no effect. Attribute axes work as soon as the attribute is populated on your products.
</Note>

## When to use diversity

Use diversity when your catalog contains many variations of the same underlying style and the first page of a collection feels repetitive. Common scenarios:

* A best-selling t-shirt is available in eight colors and all eight dominate the top of the collection.
* A top-ranked furniture piece ships in five fabrics and pushes every other product off page one.
* A vendor has multiple near-identical SKUs that all score similarly on your sort order.
* One product type (say, dresses) crowds out other types on a broad "New arrivals" collection — use a second axis on `product_type` to keep categories mixed alongside a family cap.

## How diversity fits with other sort features

Diversity layers on top of your base sort order and respects higher-priority controls:

1. **Pins** (merchandised or dynamic) stay in their pinned position and count toward the cap — a pinned family member reserves a slot under the per-family limit.
2. **Priority rules** (promote/demote) apply first, producing a preliminary ordering.
3. **Diversity** reshuffles within the top window to enforce the per-family cap and the coverage floor.
4. **Soft boost**, **metrics**, and **attributes** continue to determine ordering within the window.

## Configuration parameters

You configure diversity as an expression in two places:

* In a **sort order**, as a sorting attribute of type *Diversity*.
* In a **merchandising rule**, as an expression of type *Diversity*.

The UI exposes the same fields in both locations.

### Diversity axes

Each axis defines one dimension the expression will spread across. Add up to five axes to the same diversity expression — for example, one axis on product family and a second on product type.

Every axis has two settings:

* **Group by** — Either **Product Family** or **Attribute**. Attribute axes require you to pick an attribute (typically a categorical one like `product_type`, `vendor`, or a color feature).
* **Max per group** — The maximum number of products that can share the same value on this axis inside the window.
  * **Range:** 1 to 10 in the editor (1 to 100 accepted in payloads).
  * **Default:** 2.

When multiple axes are configured, a product only enters the top window if it stays under **every** axis cap simultaneously. That means adding a second axis makes the mix stricter, not looser — start with one axis and add more only when a single group dimension isn't enough.

<Tip>
  Existing single-axis diversity expressions keep working unchanged. When you open one in the editor, Layers shows it as a single "Axis 1" card; click **Add Axis** to introduce a second dimension.
</Tip>

### Window size

The number of top positions where the cap and coverage rules apply. Beyond this window, natural sort order resumes and repeats are allowed.

* **Range:** 1 to 200
* **Default:** 20
* **Guidance:** Match the window to the first page of your collection grid. If your storefront shows 24 products per page, a window of 24 is a reasonable starting point.

### Minimum unique families

A coverage floor. If fewer than this many distinct families appear in the window after the cap is applied, the top-scoring first-occurrence of each missing family is promoted up to fill the gap.

* **Range:** 0 to 200
* **Default:** 0 (coverage disabled)
* **Guidance:** Use when you want to guarantee a minimum breadth on the first page — for example, *"I want at least 10 different styles in the top 20."*

### Products without a group

Controls how products that have no value on an axis (for example, no family assignment or a missing attribute) are treated inside the window.

* **Treat each as its own group (recommended)** — Every ungrouped product counts as a singleton. It never trips the per-group cap and each one counts toward the coverage floor. This is the default.
* **Exempt from diversity entirely** — Ungrouped products bypass the cap and do not count toward coverage. They keep their natural sort position within the window.

## Examples

### Cap color variants on a best-seller collection

A "Best Sellers" collection keeps surfacing the same hoodie in every color. You want at most two variants of any one style in the top 20.

**Settings**

* Window size: **20**
* Axis 1: Group by **Product Family**, Max per group **2**
* Minimum unique families: **0**
* Products without a group: **Treat each as its own group**

**Result:** At most two products from any single family (for example, the hoodie) appear in the first 20 positions. The third-best-selling color drops out of the top window and re-enters below it. Products without a family are unaffected.

### Guarantee at least 10 distinct styles in the top 20

You want the first page of a seasonal collection to always feel broad, even if a handful of styles outperform everyone else.

**Settings**

* Window size: **20**
* Axis 1: Group by **Product Family**, Max per group **2**
* Minimum unique families: **10**

**Result:** After the per-family cap is applied, if the top 20 contains fewer than 10 distinct families, Layers promotes the highest-scoring first-occurrence of each missing family up into the window until the floor is met.

### Brand-level diversity

You use a manual family to group everything from a single private-label brand so it cannot dominate the top window.

**Settings**

* Window size: **24**
* Axis 1: Group by **Product Family**, Max per group **3**
* Minimum unique families: **0**

**Result:** No more than three products from the grouped brand appear in the first 24 positions.

### Mix families and product types on a broad landing collection

Your "New arrivals" collection surfaces the newest products across the whole catalog, but the first page keeps filling up with dresses from one or two families. You want variety on both dimensions.

**Settings**

* Window size: **20**
* Axis 1: Group by **Product Family**, Max per group **2**
* Axis 2: Group by **Attribute** → `product_type`, Max per group **4**
* Minimum unique families: **0**

**Result:** Products only enter the top 20 if they fit under *both* caps — no more than two products from the same family *and* no more than four products of the same product type. A third dress from any family, or a fifth dress overall, drops out of the window and re-enters below it.

## Best practices

* **Start with defaults.** A window of 20 and a cap of 2 on a single family axis works well for most apparel and home collections.
* **Add axes one at a time.** Extra axes only make the mix stricter. Ship a single-axis rule first, preview it, and only add a second axis if one dimension isn't enough to break up the top window.
* **Preview every change.** Diversity noticeably reshuffles the first page — always use the [sort order preview](/platform/sorting/preview) or [merchandising rule preview](/platform/merchandising/preview) before saving.
* **Check family coverage first.** Diversity has no effect on products that aren't assigned to a family. Before tuning, confirm that your families cover the products you care about.
* **Use coverage sparingly.** A high coverage floor can push weak matches into the top window. Raise it gradually and verify the preview still looks right.
* **Combine with priority rules, not against them.** A priority rule and a diversity expression in the same sort order can compose well — promote a brand with a priority rule, then cap variants with diversity.

## See also

* [Product families](/platform/product-families)
* [Create a product family](/help/product-families/create-product-family)
* [Sort orders](/platform/sorting)
* [Merchandising rules](/platform/merchandising)
* [Priority rules](/platform/sorting/priority-rules)