Facet drop-down menus

Learn how to display your facets as dropdowns with InstantSearch.js.

All Search and Discovery user interfaces display, in addition to a search box, a series of filters that allow users to narrow down their search. These onscreen filters are called facets. A typical facet is an attribute like “brand” or “price”, and facet values are the individual brands and prices. By clicking on a facet value, users can include and exclude whole categories of products. For example, by selecting “Blue” in the “Color” facet filter, a user can exclude every product except blue ones.

For a long time, ecommerce websites have been displaying facets on the left side of the screen, allowing easy access. But this placement reduces the space available to display products. With the rise of mobile-first design and touchscreen, online businesses have started to display facets at the top of their product listing.

That’s the case of Lacoste which increased its sales by +150% sales with Algolia’s search.

Dropdown faceting offers two benefits:

• It increases facet visibility and accessibility, encouraging more usage.
• It simplifies the screen, leaving more room for products and creating more on-screen breathing space, an important UX design choice.

This guide shows how to turn a facet filter, commonly represented by a refinementList or a hierarchicalMenu, widget, into a custom widget with a drop-down menu layout.

The provided code uses InstantSearch.js, which can be taken as-is or as a reference if you want to replicate the same pattern using Vue InstantSearch.

Wrapper elements

By design, each drop-down menu refinement widget wrapper has two elements:

• A button with a label and facet count
• A drop-down menu box

Both can be customized using settings. Each of the drop-down menu come wrapped in its own div, which allows multiple facets in the same container, thus creating a horizontal list.

To ease the creation of a drop-down menu widget, this guide provides a factory wrapper function called createDropdown that takes two parameters:

• The refinement widget you want to turn into a drop-down menu
• An object for optional settings

This function, located in the src/Dropdown.js file, returns an InstantSearch widget that can be placed alongside other widgets on your search screen.

All examples in this guide assume you’ve included InstantSearch.js in your web page from a CDN. If you’re using it with a package manager, adjust how you import InstantSearch.js and its widgets for more information.

JavaScript

const myFacetDropdown = createDropdown(instantsearch.widgets.refinementList, {
  /* optional settings */
});

Quickstart

First, you create your own drop-down menu widget. Later, you customize it. To create the drop-down menu, use a refinementList widget on your type facet.

1. Prepare the HTML

   • Import all JavaScript files, such as Algolia search, InstantSearch.js, and your own JS files.
   • Declare a placeholder div with the ID type for the drop-down menu widget for the type facet.

   In index.html:

   HTML

   <div class="container">
     <div id="searchbox"></div>
   
     <!-- Container where will be added all Dropdown facet filters -->
     <div class="search-panel__filters">
       <!-- ... -->
       <div id="type"></div>
       <!-- ... -->
     </div>
   
     <div id="hits"></div>
   </div>
   

2. Create the widget

   Import the createDropdown function from the src/dropdown.js file before initializing an InstantSearch instance with your Algolia credentials and create the drop-down menu widget.

   In this case, use a refinementList widget for the type facet. As a result, you create a customized refinementListDropdown widget for the type facet that can also be re-used for other facets.

   In src/app.js:

   JavaScript

   import { createDropdown } from "./Dropdown";
   
   // Create the refinementListDropdown widget
   const refinementListDropdown = createDropdown(
     instantsearch.widgets.refinementList,
     { closeOnChange: true },
   );
   

   Here, instantsearch.widgets.refinementList refers to InstantSearch’s refinementList widget. See the widget reference guide.

3. Add your custom widget to the InstantSearch instance

   Now that you’ve created your refinementListDropdown widget, you’re ready to add it to your InstantSearch instance.

   JavaScript

   // Initialize InstantSearch and your widgets
   search.addWidgets([
     instantsearch.widgets.searchBox({
       container: '#searchbox',
     }),
   
     instantsearch.widgets.hits({...}),
   
     // Adding the refinementListDropdown widget on the `type` facet
     refinementListDropdown({
       container: '#type', // The CSS Selector of the DOM element inside which the widget is inserted.
       attribute: 'type',  // The name of the attribute in the records.
       searchable: true    // Whether to add a search input to let users search for more facet values.
     }),
     ...
   ]);
   
   search.start();
   

By design, the createDropdown function creates a widget that acts as a wrapper around the initial widget, which is passed as a parameter. That’s why the created refinementListDropdown widget can take any of the settings available in the refinementList widget. For example, { limit: 5, showMore: true } limits the default number of displayed facet values to “5”.

Settings

The createDropdown function takes two parameters:

• Required: a refinement widget to turn into a drop-down menu
• Optional: an object with settings

JavaScript

createDropdown(
  baseWidget,
  ({ cssClasses, buttonText, buttonClassName, closeOnChange } = {}),
);

cssClasses

Type: object

An object that lets you override the CSS class in your code. Here’s an example with default values:

JavaScript

cssClasses = {
  root: "ais-Dropdown",
  button: "ais-Dropdown-button",
  buttonRefined: "ais-Dropdown-button--refined",
  closeButton: "ais-Dropdown-close",
};

buttonText

Type: string | function

This is the text displayed in the DropDown button. It can be a string or a function. By default, it shows the price of the active price refinement. Here’s an example from the priceMenuDropdown widget.

JavaScript

buttonText({ items }) {
  const refinedItem = (items || []).find(
    (item) => item.label !== "All" && item.isRefined
  );
  return refinedItem ? `Price (${refinedItem.label})` : "Price menu";
},

buttonClassName

Type: string

Same as buttonText, but for the button CSS class name. Here’s an example from the priceMenuDropdown widget.

JavaScript

buttonClassName({ items }) {
 const isRefined = (items || []).find(
   (item) => item.label !== "All" && item.isRefined
 );
 return isRefined && "ais-Dropdown-button--refined";
},

closeOnChange

Type: boolean | function

This argument can be a boolean or a function that returns true if you want the drop-down menu to close as soon as a user selects a value. If it’s false, it doesn’t close automatically, thus enabling users to select more than one facet value. Here’s an example in which the code returns true if users are using a mobile device.

JavaScript

const MOBILE_WIDTH = 375;
/* ... */
closeOnChange: () => window.innerWidth >= MOBILE_WIDTH;

Customize the UI

The generated markup lets you customize the look and feel to your needs, to change the default aspect of the drop-down menu with a few lines of CSS. Here’s the default version:

You can customize two aspects:

• Inline facet values

  The brandDropdown widget uses an inline list. See the code in app.css.

  
  CSS

  .my-BrandDropdown .ais-RefinementList-list {
    width: 20rem;
    display: flex;
    flex-wrap: wrap;
  }
  

• Fixed height drop-down menu

  The hierarchical categoriesDropdown widget uses a fixed height list. See the code in app.css.

  
  CSS

  #category .ais-HierarchicalMenu {
    height: 195px;
    overflow: auto;
  }
  

Mobile support

On mobile devices, more than anywhere else, displaying facet refinements over the results is a must-have, considering the limited real estate. Drop-down widgets are a great fit, but you need to tweak the display so they can take advantage of the screen’s width and height.

The mobile version uses the following CSS media query:

CSS

@media only screen and (max-width: 375px) {
  /* ... */
}

It uses the following JavaScript settings at each widget level:

JavaScript

const MOBILE_WIDTH = 375;

const refinementListDropdown = createDropdown(
  instantsearch.widgets.refinementList,
  { closeOnChange: () => window.innerWidth >= MOBILE_WIDTH },
);

This demo gets you started by providing a basic look and feel for mobile devices. Refactor the provided code to match your current design and offer the best experience to your mobile users.