Category pages

Showcase a single category of your catalog using Algolia.

Category pages are product listing pages that are already filtered on. The product listing page is a gateway to the product detail page.

Examples of category pages include:

• On Sale
• New Arrivals
• Brands
• Product types
• Items for certain gender, size, or color

This guide shows you how to implement category pages:

• Using the API client or REST API
• Using InstantSearch on the frontend

High-level approach

• You create a category page by sending an API request with an empty query and a filters parameter based on a category page identifier.
• The API response returns a list of products based on the category page identifier in the hits attribute.

Implementation steps

1. Create a data attribute that references the category page for each record

   You can create category pages using different combinations of filter values. Although Algolia doesn’t impose any restrictions on the amount of filters you pass, best practice is to tag each item with an array of category page identifiers.

   A category page identifier is a unique identifier that references a particular category page. It can be a string or an integer. You can name it categories, categoryId, categoryPageId or anything else. Importantly, you can automate tagging the records with the category page identifier to ensure that the right products always show up on the right category pages. You use this identifier:

   • In the query, to filter on the product index to generate each category page
   • As a category page reference, for visual merchandising in the dashboard

   It’s best to set the category page identifier to something more prescriptive such as On Sale or Women > Clothing > Dresses. This way, business users, when merchandising, can easily reference the category page based on a less technical name.

   Look at the sample record below. This item belongs to multiple category pages:

   JSON

   {
     "objectID":"1696302",
     "name":"Nike Blue Joggers on Sale",
     "categoryPageId": [
       "On Sale",
       "New In",
       "Summer Clearance",
       "Clothing",
       "Nike",
       "Clothing",
       "Clothing > Men",
       "Clothing > Men > Pants",
       "Clothing > Men > Pants > Joggers"
     ],
     "brand":"Nike",
     "hierarchicalCategories": {
       "lvl0": "Clothing",
       "lvl1": "Clothing > Men",
       "lvl2": "Clothing > Men > Pants",
       "lvl3": "Clothing > Men > Pants > Joggers"
     },
     "color": "Blue",
     "inStock":true,
     "visibility": true,
     "summerClearance": true,
     "onSale": true,
     "newArrival": true,
     "description":"....",
     "price":70,
     "image":"...jpg"
   }
   

   For example, here are sone filters you can apply for different category pages:

   Page Type	Method A: Filter on multiple attributes	Method B: Filter on Category Page ID (Recommended)
   On Sale	- onSale: true - inStock: true	- categoryPageId: On Sale
   Summer Clearance	- summerClearance: true	- categoryPageId: Summer Clearance
   New Arrivals	- newArrival: true - arrivalTime > [timestamp] - inStock: true	- categoryPageId: New in
   Product Collections	- hierarchicalCategories.lvl0: Clothing - inStock: true	- categoryPageId: Clothing
   Brand Collections	- brand: Nike - inStock: true	- categoryPageId: Nike
   Hierarchical Categories (Top / Subcategories)	- hierarchicalCategories.lvl1: Clothing > Men - inStock: true	- categoryPageId: Clothing > Men
   Items for certain gender or size	- Gender: Men - hierarchicalCategories.lvl2: Clothing > Men > Pants - inStock: true	- categoryPageId: Clothing > Men > Pants

   It’s best to use method B for two reasons:

   • To use the Category Merchandising feature in the Visual Editor, your dataset must contain a unique category page identifier.
   • Having a unique ID per category page makes it easier for merchandisers to reference the page and to merchandise products accordingly.

   If you use method A, you can’t use the Category Merchandising feature in the Visual Editor. Using method A, introduces room for errors for business users. Business users who use the Visual Editor to create merchandising rules have to take an additional step to add inStock: true or visibility: true as a Rule condition for every rule. Avoid that complexity by automatically updating the category page identifier for each record.

   For more information, see:

   • Prepare your records for indexing
   • What’s a facet?
   • Hierarchical facets
2. Keep category ientifiers up to date

   Set up data synchronization to automate the process of keeping records up to date with the right category page identifier

   To keep records updated with relevant values, push a partial update on the categoryPageId attribute based on stock availability or other dynamic values that affect the visibility of products on a given page. Partial record updates lets you change only some attributes, in this case categoryPageId, which improves indexing performance.

   C#

   var response = await client.PartialUpdateObjectAsync(
     "ALGOLIA_INDEX_NAME",
     "productId",
     new Dictionary
     {
       {
         "categoryPageId",
         new Dictionary
         {
           { "_operation", "Add" },
           { "value", "men-clothing-pants" },
         }
       },
     }
   );
   

   To remove products from a particular category page:

   C#

   var response = await client.PartialUpdateObjectAsync(
     "ALGOLIA_INDEX_NAME",
     "productId",
     new Dictionary
     {
       {
         "categoryPageId",
         new Dictionary
         {
           { "_operation", "Remove" },
           { "value", "men-clothing-pants" },
         }
       },
     }
   );
   

3. Configure your index

   Declare categoryPageId as a searchable attributesForFaceting. You can do this using the API or the dashboard.

   Using the dashboard

   To add categoryPageId as a searchable attributesForFaceting, follow these steps:

   1. Select the Search product icon on your dashboard and then select your index.
   2. Click the Configuration tab.
   3. In the Facets subsection of Filtering and Faceting, click the Add an attribute button and select the categoryPageId attribute from the drop-down menu.
   4. Set searchable facet on categoryPageId.
   5. Save your changes.
4. Build the query

   The query should include the following:

   • Empty string
   • Facet filter on categoryPageId
   • Analytics tags, which lets you view in the dashboard the click and conversion performance of specific category pages

   C#

   var response = await client.SearchSingleIndexAsync(
     "ALGOLIA_INDEX_NAME",
     new SearchParams(
       new SearchParamsObject
       {
         Filters = "categoryPageId: Men's Clothing",
         HitsPerPage = 50,
         AnalyticsTags = new List { "mens-clothing" },
       }
     )
   );
   

5. Optional: build a frontend UI with InstantSearch

   To apply the query parameters in the frontend, instantiate the configure widget and add the parameters from the previous Build the query step.

   JavaScript

   InstantSearch.widgets.configure({
     filters: "categoryPageId: 'Men\'s Clothing'",
     hitsPerPage: 50,
     analyticsTags: ['browse', 'mens-clothing']
   });
   

Next steps

After configuring category pages, you can add Rules to curate them, you can use Dynamic Re-Ranking to adjust the order of categories dynamically, or you can personalize the category pages.

• Merchandise category pages
• Add Dynamic Re-Ranking to category pages
• Personalize results