Faceted Search

We've made it super easy to add faceting to your search forms. To set it up, you just need to follow 3 simple steps :

QuickJump:

1. Define the facet attributes in Algolia

The first step is to define exactly what should be facet-able when searching. To do this, just visit the specific index in your algolia dashboard, and go to the Display tab.

In that tab, find the Faceting heading, and the first input called Attributes for faceting. In here we'll add the specific attributes you want to use.

For example, if we had our data setup with data that included categories, type and brand and we wanted these as our facets, we'd set that input up like this :

With that setup, just click the Save button for algolia to start working on your new settings.

You can come back and update these facets later, and you don't explicitly need to expose facets defined here to the actual end-users on your search form. We'll control that later in our init code.

2. Setup the facets template

Now that we have our facets setup on the index, we need a way to actually mark them up on the page. This works exactly the same as our results template, but this time, just using the id of facet-template.

Here's our example facet template for reference : 

<!-- Facet template -->
<script type="text/template" id="facet-template">
    <h4>{{ title }}</h4>
    <div class="product-search-facet-row">
        {{#values}}
        <div class="checkbox toggle-refine {{#isRefined}}facet-refined{{/isRefined}}"  data-facet="{{ facet }}" data-value="{{ name }}">
            <label>
                <input type="checkbox" {{#isRefined}} checked{{/isRefined}}>
                {{ name }}
            </label>
        </div>
        {{/values}}
    </div>
    <hr/>
</script>

To highlight the key parts in that template snippet :

  • The template snippet has an id of facet-template
  • The available facet options are handled in the {{#values}}..{{/values}} block
  • Each facet has a class of toggle-refine which is what's keyed against for triggers
  • Each facet has a data-facet and data-value attribute, which is where the actual facet details are stored
  • We can show the current state of a facet using the {{#isRefined}}..{{/isRefined}} block

3. Add the facets to your init js

Nearly there! The very last step is just to add the specific facet's we want exposed on the page to our searchplus helper js init.

We just need to update our call to $(this).searchplus(); to include the facets we want to expose. We do that by passing the facets parameter on the init call. Like this : 

$(this).searchplus({
    facets : ['categories', 'type', 'brand']
});

And hey presto! That's all you need to do for full facets on your indexes.

There's a few extra things we might want to tweak to alter the behaviour, like adding the facet labels using the facetsLabels parameter, or changing the maximum number of facet options to show for each set, with the maxValuesPerFacet option, so we might end up with something like : 

$(this).searchplus({
    facets : ['categories', 'type', 'brand'],
    facetsLabels: { 'categories' : 'Categories', 'type' : 'Product Type', 'brand' : 'Brand' },
    maxValuesPerFacet: 15
});

There's more options too, if we want to keep tweaking the behaviour, but this is all you really need to understand to get going with faceting.

Checkout the full javascript options for more details on setup options.

Helper Reference →