Category listing with Search.js

Search.js can be used to render rich, interactive category listings. A category listing is a search where the initial view is pre-filtered for a specific category and no user-typed query is present. This is similar to calling the Search API directly with a filter, like /search?f[]=category:T-shirts.

The two-step process

A key aspect of using Search.js for product listings is understanding its two-step process:

1. Initialization (Luigis.Search({...})): Sets up the entire search interface — all components like facets and sorting — and links the library to your HTML placeholders. No search is performed yet.
2. Execution (Luigis.Search.Search(...)): Executes the initial search. For a listing page, you execute this with a null query but with a special IntentFilters object that tells the system what category to display.

DefaultFilters.type is required

Always set a content type in DefaultFilters:

Luigis.Search({
  TrackerId: 'YOUR_TRACKER_ID',
  DefaultFilters: {
    type: 'product' // required -- use your own catalog's type name
  }
}, '#search-input', '#search-ui');

Search.js sends this as the f[]=type:product filter on every request. Your catalog holds more than products — categories and brands live in the same index — so without it the listing is not restricted to products and its results are not reliable.

DefaultFilters is also what IntentFilters gets merged into, so the type filter survives the transition from browsing a category to searching.

Limiting the response with HitFields

The attribute names you list control each hit’s own attributes. If your tiles also show a product’s other variants, include 'nested' too:

HitFields: ['title', 'image_link', 'price_amount', 'nested']

Listing attribute names alone leaves nested empty. See Implementing variant search.

Implementation details

Follow the same setup as when initializing a standard search page, including the loading placeholder for the best user experience.

The key to creating the category listing is the second call, which uses the IntentFilters configuration.

Luigis.Search.Search(
  null, // The query is null
  {
    ProductListingFilter: "category_id",
    IntentFilters: { category_id: 123 }
  }
);

Parameters:

1. query (null): Use null when displaying a category listing since you want to show all products in that category, not search results for specific keywords.

2. configuration object with two key properties:

   • ProductListingFilter: Must match one of the keys used in IntentFilters. Tells Search.js which filter defines the current product listing context.
   • IntentFilters: Defines which filters to apply for the initial listing.

Caution

ProductListingFilter only needs to reference one of the keys present in IntentFilters. For category listings, prefer the attribute that best represents the page context, such as category_path or all_categories_path.

The IntentFilters are temporary and automatically clear when users start typing in the search box, seamlessly transitioning from browsing a category to searching across all products.

Complete example

<script src="https://cdn.luigisbox.com/search.js"></script>
<script>
  // 1. First, INITIALIZE the search UI
  Luigis.Search({
    TrackerId: 'YOUR_TRACKER_ID',
    Theme: 'boo',
    Facets: ['brand', 'price_amount'],
    DefaultFilters: {
       type: 'product' // required, see above
    }
  }, '#search-input', '#search-ui');

  // 2. Immediately after, EXECUTE a search for category id 123
  Luigis.Search.Search(
    null,
    {
      ProductListingFilter: "category_id",
      IntentFilters: { category_id: 123 }
    }
  );
</script>