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

# Merchandise category pages

> Create rules and apply them to merchandise category pages.

export const SearchQuery = () => <Tooltip tip="The text users enter into a search box. In the Search API, this corresponds to the query parameter. A search query is often used with filters, facets, and other parameters, but these aren't part of the query text itself.">
    search query
  </Tooltip>;

With Algolia, you can [merchandise products](/doc/guides/managing-results/rules/merchandising-and-promoting) by creating category pages.
For example, you could organize products into categories such as on-sale items, new arrivals, specific brands, product types (like smartphones), or colors.

If you want to merchandise product groups on your category pages dynamically,
see [Smart Groups](/doc/guides/compositions/smart-groups/smart-groups).

<Note>
  To use an attribute in a rule condition with filters, declare it in [`attributesForFaceting`](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting).
</Note>

## Before you begin

1. [Choose an attribute as category page identifier](/doc/guides/solutions/ecommerce/browse/tutorials/category-pages).
2. [Make that attribute searchable](/doc/guides/managing-results/must-do/searchable-attributes).
3. [Declare that attribute as a searchable facet](/doc/guides/solutions/ecommerce/browse/tutorials/category-pages#implementation-steps).

## Merchandise category pages

Merchandise category pages by configuring an identifier, setting a trigger (a condition), and selecting a strategy (a consequence).

### Configure a category page identifier

1. Go to the [**Rules**](https://dashboard.algolia.com/rules/) section in the Algolia dashboard. Select the index to which you want to add a rule.
2. Select **Create your first Rule** or **New rule**, then select **Visual Editor**.
3. In **Conditions**, select **Choose category page**.
4. Click **Configure**, then **I'm good, let's go**.
5. Select a [searchable facet](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting) as your **Category page identifier**.
6. Optional: add a **Custom subcategory separator** if you're using [hierarchical categories](/doc/guides/managing-results/refine-results/faceting#hierarchical-facets). For example, for the hierarchical category: `Women / Coat / Raincoat`, enter `/` as the custom separator.
7. **Save** your changes.

<Note>
  To update these settings later, click the gear icon in the top-right corner of the Visual Editor and select **Category page identifiers**.
</Note>

### Create a trigger

1. Go to the [**Rules**](https://dashboard.algolia.com/rules/) section in the Algolia dashboard. Select the index to which you want to add a rule.
2. Select **Create your first Rule** or **New rule**, then select **Visual Editor**.
3. In **Conditions**, select **Choose category page**.
4. Choose a **Category name**: this is a value from your category page identifier.
5. Click **Apply**.

### Determine a consequence

In **Consequences**, select [how you want to merchandise](/doc/guides/managing-results/rules/rules-overview/in-depth/implementing-rules#consequence—adapt-the-results) the category page.

* Click **Review and Publish**, review the rule, and click **Publish** to enable the category page rule.
* Click **Save as Draft** if you don't want the rule to take effect yet.

## Example: promote items on category pages until users start searching

To promote items on category pages before users start searching, create a rule that's triggered if:

* A user visits the category page
* The <SearchQuery /> is empty.

### Using the dashboard

You can create this rule from the Algolia dashboard using either the Visual Editor or the Manual Editor.

<Tabs>
  <Tab title="Visual Editor">
    1. In the Algolia dashboard, select your application and index, open **Rules**, and select **New rule > Visual Editor**.
    2. In **Conditions**, click **Set query condition(s)**.
       Toggle **Query** on, select **is**, and leave the search input empty.
       Toggle **Filters** on, select `category` as the **Filter name** and `Smartphone` as the **Value**, then click **Apply**.
    3. In **Consequences**, select **Pin items**.
       Under **Pinned items**, search for an item and enter its **Position**.
       To pin more items, click **Pin another item**.
       Click **Apply**.
    4. Review the results, click **Review and Publish**, and click **Publish**.
       To keep the rule inactive, use **Save as Draft** instead.
  </Tab>

  <Tab title="Manual Editor">
    1. In the Algolia dashboard, select your application and index, open **Rules**, and select **New rule > Manual Editor**.
    2. In **Condition(s)**, toggle **Query** on, select **Is**, and leave the search input empty.
       Toggle **Filters** on, select `category` as the **Attribute name** and `Smartphone` as the **Attribute value**.
    3. In **Consequence(s)**, click **Add consequence > Pin an item**.
       Search for an **Item** and enter its **Position**.
       To pin more items, click **Add consequence** again.
    4. Optional: add a description and a validity period.
       Save your changes.
  </Tab>
</Tabs>

## Example: display banners on category pages

Category page banners operate similarly to search results [banners](/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/add-banners), but a filter rather than a search query triggers them.

### Display a banner with InstantSearch

Use the **Display banner** consequence to show a banner in your category page's InstantSearch `Hits` or `InfiniteHits` widget.

<Note>
  This requires InstantSearch.js version 4.73.0 or later, React InstantSearch version 7.12.0 or later, or Vue InstantSearch version 4.19.0 or later.
</Note>

1. In the Algolia dashboard, select your application and index, open **Rules**, and select **New rule > Visual Editor**.
2. In **Conditions**, click **Set query condition(s)**.
   Toggle **Query** off and **Filters** on.
   Select `category` as the **Filter name** and `Smartphone` as the **Value**, then click **Apply**.
3. In **Consequences**, expand **More consequences** and select **Display banner**.
   Enter the URL for your banner image and click **Apply**.
4. Review the banner preview, click **Review and Publish**, then click **Publish**.

When your category page sends a search with the matching category filter, the rule returns banner data in `renderingContent.widgets.banners`.
The supported InstantSearch widget displays the banner unless you configure it to hide banners.
For UI integration examples, see [Render banner with InstantSearch](/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/add-banners#render-banner-with-instantsearch).

### Display a custom banner

This example returns custom banner data for your UI to display.

You can create this rule from the Algolia dashboard using either the Visual Editor or the Manual Editor.

<Tabs>
  <Tab title="Visual Editor">
    1. In the Algolia dashboard, select your application and index, open **Rules**, and select **New rule > Visual Editor**.
    2. In **Conditions**, click **Set query condition(s)**.
       Toggle **Query** off and **Filters** on.
       Select `category` as the **Filter name** and `Smartphone` as the **Value**, then click **Apply**.
    3. In **Consequences**, expand **More consequences** and select **Return custom data**.
       Enter `{ "banner": "iPhone" }` and click **Apply**.
    4. Click **Review and Publish**, then click **Publish**.
  </Tab>

  <Tab title="Manual Editor">
    1. In the Algolia dashboard, select your application and index, open **Rules**, and select **New rule > Manual Editor**.
    2. In **Condition(s)**, toggle **Query** off and **Filters** on.
       Select `category` as the **Attribute name** and `Smartphone` as the **Attribute value**.
    3. In **Consequence(s)**, select **Add consequence > Return Custom Data**.
       Enter `{ "banner": "iPhone" }`.
    4. Optional: add a description and a validity period.
       Save your changes.
  </Tab>
</Tabs>

Now, every time a user visits the category page, the rule triggers and returns a JSON object as custom data.
You can [display this custom data](/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/add-banners#retrieve-the-banner-data-in-your-ui) in your UI as a banner.

## See also

* [Category pages](/doc/guides/solutions/ecommerce/browse/tutorials/category-pages)
* [Add Dynamic Re-Ranking to category pages](/doc/guides/algolia-ai/re-ranking/tutorials/re-rank-category-pages)
* [Filters can trigger rules](/doc/guides/managing-results/rules/rules-overview/in-depth/implementing-rules#filters-can-trigger-rules)