> ## Documentation Index
> Fetch the complete documentation index at: https://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/managing-results/compositions/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

{/* vale Google.We = NO  */}

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** and select **Visual Editor**.
3. In the **It all starts here** section, 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.

{/* vale Google.FirstPerson = YES  */}

<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** and select **Visual Editor**.
3. In the **It all starts here** (trigger) section, 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 the **What do you want to do?** section, 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** 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 search 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.

### Create the rule in the Visual Editor

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** and select **Visual Editor**.
3. In the **It all starts here** section, click **Set query condition(s)**. In the **Define the condition that triggers the rule**:

   1. Toggle the **Query** option on.
   2. For **Your Search**, select **Is** and leave the text input empty.
   3. Toggle the **Filters** option on.
   4. Select a **Filter name**, for example, `category`.
   5. Select a **Value**, for example, `Smartphone`.
   6. Click **Apply**.
4. In the **What do you want to do?** section, select **Pin items**. The **Choose items to pin** pane opens:

   1. Under **Pinned items**, search for the item you wish to pin and enter a number as the **Position** to which you want to pin the item.
   2. Optional: click **Pin another item** and repeat this step.
   3. Click **Apply**.
5. Save your changes.

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

### Create the rule in the Manual Editor

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** and select **Manual Editor**.
3. In the **Condition(s)** section:

   1. Toggle the **Query** option on.
   2. Select **Is** from the menu and leave the text input empty.
   3. Toggle the **Filters** option on.
   4. In the **Attribute name** field, select the category page identifier, for example, `category`.
   5. In the **Attribute value** field, select the category you want to merchandise, for example, `Smartphone`.
4. In the **Consequence(s)** section:

   1. Click **Add consequence > Pin an item**.
   2. Search for an **Item** you want to pin and define its **Position**.
   3. Optional: click **Add consequence** to pin more items.
5. Optional: enter a description that describes what the rule does and enter a period during which the rule is valid.
6. **Save** your changes.

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

<Note>
  This example requires a UI that uses the [`Hits` widget](/doc/api-reference/widgets/hits/js) from InstantSearch.js version 4.68.1 or later or Reach InstantSearch version 7.8.0 or later.
</Note>

### Create the rule in the Visual Editor

1. Create a [trigger](#create-a-trigger).

2. In the **Consequences** section:

   1. Click **Display banner**.
   2. Enter the **Image URL** for your banner and click **Apply**.

3. Optional: enter a description that describes what the rule does and enter a period during which the rule is valid.

4. Apply your changes.

A banner now displays on every visit to this category page.

### Create the rule in the Manual Editor

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** and select **Manual Editor**.

3. In the **Condition(s)** section:

   1. Toggle the **Filters** option on.
   2. Toggle the **Query** option off.
   3. In the **Attribute name** field, add your category page identifier, for example, `category`.
   4. In the **Attribute value** field, add the category for which you want to show a banner, for example, `Smartphone`.

4. In the **Consequence(s)** section:

   1. Select **Add consequence > Return Custom Data.**
   2. In the input field, enter a JSON object, for example, `{ "banner": "iPhone" }`.

5. Optional: enter a description that describes what the rule does and enter a period during which the rule is valid.

6. Save your changes.

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)