Clerk.io Developer Documentation

Welcome to the Clerk.io Developer Documentation.

Here you find our developer documentation for our API and all our SKDs.

Get Started    

Faceted Search

Faceted navigations help your customers easily filter through your results.

Clerk.js comes with built-in support for dynamic faceted navigation for both search and recommendations.

Any product attributes you send to us can be used as part of the facets.

Clerk.js has by default build in the bestin-class UX components for easy filtering.

Basic usage

Facets will be enabled on any Content with the data-facets-target and data-facets-attributes attributes.

Let's start with a quick example of using facets on a search page:

<div id="clerk-search-filters"></div>

<span 
  class="clerk" 
      
  data-template="@search-page" 
  data-query="shoes"
  
  data-facets-target="#clerk-search-filters" 
  data-facets-attributes='["price","categories","brand"]'
  data-facets-titles='{"price": "YOUR-PRICE-LABEL-TRANSLATION-GOES-HERE", "categories": "YOUR-CATEGORIES-LABEL-TRANSLATION-GOES-HERE", "brand": "YOUR-BRAND-LABEL-TRANSLATION-GOES-HERE"}'
  data-facets-price-prepend="€">
</span>

In this example, a facet menu will be injected into the div#clerk-search-filters element.

Attribute

Value

data-facets-target

A css selector pointing to the element that should contain the facet filter menu.

data-facets-attributes

The product attributes that should be used as facets.

data-facets-price-prepend

If present, prepends the price facets (if present in attributes) with this value. e.g. '€', 'DKK'

data-facets-price-append

If present, appends the price facets (if present in attributes) with this value. e.g. '€', 'DKK'.

Customising facets titles

By default, facet titles will just be the title case of the attribute name eg the attribute price will be shown with the title Price.

If you wish to change any title you can do it via the data-facets-titles attribute that is already embedded in the snippet above.

Attribute

Value

data-facets-titles

Takes a JSON encoded dictionary of an attribute, title pairs eg. data-facets-titles='{"on_sale": "On Sale", "colors":"Color"}'

Customising look and feel

Facets come with a best-practice styling out of the box that's deliberately build to look good on all websites.

To enable easy customisation everything can be overwritten with CSS.

Below are the CSS classes for the different UX elements.

CSS Selector

Description

.clerk-facets

The main facet container.

.clerk-facet-group

The container a facet group.

.clerk-facet-group-title

The title element of a facet group.

.clerk-facet-group-facets

The container element of all the facets in the facet group.

.clerk-facet

The container of a single facet.

.clerk-facet-name

The element containing the facet name.

.clerk-facet-count

The element containing the facet count.

Quick Tip: An easy way to add your colors to the selected facets and ranges would be to simply replace the color code #AABBCC with the color code your site uses.

.clerk-facet-name:hover:before, .clerk-range-selected-range {
  background-color: #AABBCC;
  border-color: #AABBCC;
}

Selecting multiple values

By default, we try to narrow down the facets as much as possible only showing the facets matching all previous selections. But sometimes you would like customers to select multiple values such as with sizes or colors.

Any attribute where you want customers to be able to select multiple values you just add then to the attribute data-facets-multiselect-attributes.

Attribute

Value

data-facets-multiselect-attributes

A list of the attributes for with you would like to enable multiselection eg. data-facets-multiselect-attributes='["price","colors"]'.

Updated 13 days ago

Faceted Search


Faceted navigations help your customers easily filter through your results.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.