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

# Product Grouping in a Recommendation Widget

Product grouping splits a single recommendation widget into tabs — one tab per category, brand, or any other product attribute. It's the right pattern for a homepage block where you want to show bestsellers across several departments without taking up six separate widget slots.

This guide walks through enabling grouping, picking a grouping attribute, configuring the visible tabs, and styling the tab bar for desktop and mobile.

## When to use grouping

Grouping makes sense when:

* You want to surface recommendations across multiple categories from a single widget (for example, a homepage "Top picks" block with tabs for Women, Men, Kids).
* You're using a category-aware algorithm like Popular Products by Category and want all categories to render at once.
* You want visitors to self-select what they're interested in without scrolling through unrelated cards.

It's less useful for product pages or cart widgets, where the customer's context already points at a specific kind of product.

## Enable grouping

<Steps>
  <Step title="Open the widget">
    Go to **Personalization → Recommendation widgets** and open the widget you want to edit.
  </Step>

  <Step title="Find the grouping setting">
    In the widget's appearance settings, locate the **Recommendations grouping** option.
  </Step>

  <Step title="Turn grouping on">
    Toggle the option on. New configuration fields appear below it.
  </Step>
</Steps>

## Choose the grouping attribute

You can group products by any of these attributes:

* **Product name** — useful for showing variants grouped together.
* **Price** — splits products into price tiers (rarely useful for a tab UI, more common for filters).
* **Manufacturer / brand name** — one tab per brand.
* **Discount** — separates discounted and full-price items.
* **Primary category** — the most common choice for a homepage block.
* **Custom field** — any custom product field, referenced by its system name (for example, `gender`, `season`, `collection`).

For a homepage bestsellers block, primary category is almost always the right pick.

## Specify which values to show as tabs

By default, the widget creates a tab for every distinct value of the chosen attribute that appears in the algorithm's output. To control the order and limit which tabs appear, list the values explicitly as a comma-separated list:

```
women, men, kids, accessories
```

A few things to know:

* The list is **case-insensitive** — `Women`, `women`, and `WOMEN` all match the same value.
* The order in the list is the order tabs appear in the widget.
* Values not on the list are excluded from the widget (unless you enable "Other" — see below).

<Note>
  If none of the products returned by the algorithm match the values you listed, the widget falls back to showing all available categories. This prevents the widget from rendering empty — better to show something than nothing.
</Note>

## The "Other" group

Enable the **"Other" group** option when you want products that don't match any of the listed values to still appear — bundled into a single catch-all tab. You can set the display name (for example, `More`, `Everything else`, or `Other`).

Use cases:

* You list the top three categories explicitly and let everything else fall into "More".
* You're running a seasonal block (`summer`, `fall`) and want non-seasonal items grouped together.

## Style the tab bar

Tab bar styling is configured separately for mobile and desktop, so you can tune sizes for each viewport. Adjustable properties include:

* **Tab font size** and **font weight**.
* **Tab padding** and **gap** between tabs.
* **Active tab indicator** — underline color, thickness, and offset.
* **Tab text color** — separate values for inactive and active states.
* **Background** — fill behind the tab bar.

<Tip>
  On mobile, set the tab bar to scroll horizontally rather than wrapping. Wrapped tabs eat vertical space above the fold; a horizontal scroll keeps the bar compact and lets visitors see all categories with a swipe.
</Tip>

## Finish the setup

Once grouping is configured:

<Steps>
  <Step title="Pick the website">
    Choose the site this widget belongs to (for multi-site projects).
  </Step>

  <Step title="Pick the product system">
    The catalog source the algorithm draws from.
  </Step>

  <Step title="Pick the algorithm">
    A category-aware algorithm like **Popular Products by Category** pairs naturally with category grouping.
  </Step>

  <Step title="Set the display location">
    Either embed via CSS selector or paste the container code into your site template.
  </Step>

  <Step title="Test on the test link">
    Open the widget's test link and verify each tab loads its own products, the tab styling looks right on both desktop and mobile, and switching tabs is smooth.
  </Step>

  <Step title="Launch">
    Activate the widget once everything checks out.
  </Step>
</Steps>

## Common pitfalls

<AccordionGroup>
  <Accordion title="Tabs show but they're empty">
    The algorithm isn't returning products for that category. Confirm the category has in-stock products and that the algorithm's source segment (if any) doesn't exclude them.
  </Accordion>

  <Accordion title="Tab order is wrong">
    The comma-separated value list controls order. Re-order the list and save.
  </Accordion>

  <Accordion title="A tab is missing">
    Either the value isn't in the list, or no products in the algorithm output have that value. Check both.
  </Accordion>

  <Accordion title="The widget shows all categories instead of just my list">
    None of the products in the algorithm output match your listed values, so the widget fell back to "show everything" to avoid rendering empty. Either broaden your list or check that the algorithm is returning the categories you expect.
  </Accordion>
</AccordionGroup>

## Next steps

* [How to Create a Recommendation Widget](/personalization/recommendation-widgets/how-to-create-a-recommendation-widget) — full widget setup walkthrough.
* [How to Style a Recommendation Widget](/personalization/recommendation-widgets/how-to-style-a-recommendation-widget) — product card markup and CSS guidelines.