Get Started with Facets

Faceted navigation refers to the use of refinement options on search results. A facet refers to the something particular about an item, such as its color, size and price. For sites that offer even a small variety of products, facets empower shoppers to find the product that is right for them.

Setting Up Facets

You set up new facets for your site in the backend. Go to Setup > SuiteCommerce Advanced > Set Up Web Site. After selecting your site from the list, go to the Search Index tab, then the Facet Fields subtab. The ones on my site look like this:

My site is primarily a retail fashion site, so I run facets for size, color and price. If I were to use these on my site using only the default settings then it wouldn't be particularly user friendly. For example, look at the image below which is how those three facets would appear on the site.

So let's look at the options available for facets.

Configuring Facets

This is where SC.Shopping.Configuration.js comes in. This frontend configuration file, contains a number of settings that apply directly to facets and how they work. To start with, let's look at the settings that will immediately improve the look of these components.

We include three styles for facets:

  1. facets_faceted_navigation_item_range.tpl
  2. facets_faceted_navigation_item_color.tpl
  3. facets_faceted_navigation_item.tpl

The final one is the default template for when the first two are not appropriate. In short, the default template is a simple, functional template that displays each value as an individual item to be selected. Judging by the names of the others, you'll see that the first two are only applicable in specific circumstances: ranges of values (i.e., upper and lower price range) and colors. Thus it is easy to see why the default template won't work with prices and colors: each individual price would have to be selected, and colors are by definition visual things — it is best to represent them as such.

The main place for configuring facets is the facets object in the frontend shopping configuration file. If this object is empty, or you don't add settings for a particular facet, then the defaults will be used. I'm going to talk a little about this object, but only the basics.

Color Picker

To start with, lets look at how we style the color picker. Let's look at the following code for color picker:

,   {
        id: 'custitem31'
    ,   priority: 20
    ,   name: _('Color').translate()
    ,   template: facets_faceted_navigation_item_color_tpl
    ,   colors: colors

So, here we're defining the mysterious custitem31, which happens to be the internal ID of the custom field my site uses for product colors (this may be different on your site). Also note that if you've set up names for URL components, then this could be something else, such as color.

Next, we've set a value for priority. This determines what order to display the facets in. The larger the number, the closer to the top it'll appear. If you don't set a value then it'll be added after all the other facets which have a priority value.

Then we set the name of the facet. Simply, this is the name of what you want to appear as the title for it. if you set nothing, it'll use the ID of the facet as the title.

Now an important one: the facet template. I've already talked about the possible values for this, but you'll notice we've specified the special template for the color picker — this will override the default.

Finally, we've added colors: colors. The colors value is a variable declared at the top of the file which contains an array of key/value pairs that associates names of colors with appropriate hex codes.

As that's now sorted out. When I reload my site, I can see it take effect:

Price Slider

As mentioned above, you want a price slider because the idea of customers having to select each individual price would be very frustrating. No shopper enters an online store and thinks, "I want a shirt that is precisely $39.74"; it is more far more likely that they'll think something like, "I want a shirt that is $30-40".

Thus, the code for implementing the slider should look something like the following:

,   {
        id: 'pricelevel5'
    ,   name: _('Price').translate()
    ,   priority: 10
    ,   behavior: 'range'
    ,   template: facets_faceted_navigation_item_range_tpl
    ,   uncollapsible: true
    ,   titleToken: 'Price $(1) - $(0)'
    ,   parser: function (value)
            return _.formatCurrency(value);

You'll be familiar with the fields we covered already. However, note, again, that the value id key depends on whatever price you're using on your site.

The behavior key determines how the facet works in the browser. Here we're overriding the default behavior of selecting a single option with the ability to accept upper and lower bounds.

By default, facets are 'collapisble', which means that they can be minimized in the list of facets (characterized by upward or downward facing chevron). For facets that you consider important or small, you can specify that they are uncollapsible, meaning that this UI feature is disabled and the facet is permanently visible.

titleToken defines how the title tag will be updated when the facet is active on the search results. $(1) and $(0) refer to the selected lower and upper values, respectively.

Finally, the parser property accepts a function that adds context to the values returned. As we're dealing monetary values, we're telling the browser to format the values as currencies, thus it will return the shopper's currency symbol.

With those settings in place, let's see how it looks.

Extension Ideas

For the final facet on my site (size) is the only one unstyled. However, it should be clear how I might style it. After all, it's neither a range nor a color palette so it'll use the default template. As for other settings, we may want to make use of the multi value with the behavior key. This enables the shopper to select multiple options: perhaps if they're between sizes.

Custom Facet Templates

You may be interested in creating your own facet templates. You may have noticed at the top of SC.Shopping.Configuration.js that we include the special templates as dependencies.

I won't walk you through the process of adding a new facet template but in summary:

  1. Set up a new module as you would any other customization (folder structure, ns.package.json file, updating distro.json etc.).
  2. Create a new template file. Give it a unique name but you'll probably want to follow the convention of the others.
  3. To start, copy and paste the contents of facets_faceted_navigation_item.tpl into the new template file.
  4. Add your new template file as a dependency to the configuration file, assign it to a facet and test that it works. You may need to add an arbitrary change to the template be sure that it's working.
  5. Make your modifications as you wish. If you need to (which you probably will) then you can also modify the class names and add your own Sass file to accompany it.

Now that you have this in place, think about the types of special templates you'd like to make. You don't have to, of course, but perhaps you'll find that, like the color swatches and price slider, there are cases where a special template is required.

Custom Facet Colors

The key concept is that you shouldn't replace the colors object. Instead, you should extend it thusly:

, colors: _.extend(colors,{'red':'#ff0000'})

In this example, this will replace the hex for the red color with a new one.

On that note, be aware that you're not confined by hex codes. Essentially, the value you provide is fed into the template and applied to a span using the background CSS property. Therefore, if you wish to, you can specify any value for a color as long as it's a valid value.

So, for example, some of the products on my site are multicolored. The multi key is not defined in my colors object, so if I wanted to add it then I could do the following:

,   colors: _.extend(colors,{'multi': 'repeating-linear-gradient(45deg,red,green 0.5em,blue 0.5em,yellow 1em)'})

This creates a gradient image that resembles a rainbow spectrum (see the swatch in the middle):

Finally, note that there is some extra styling available for light colors. The lightColors array is meant for when you want to specify colors (already in the colors object) that have a similar hue to the background color of the search results. This means, for example, that in the template you can apply a border to these colors so that they stand out a little more.


Facets are a vital tool in search results: they provide shoppers with the ability to refine and find the products they're looking for quicker and easier.

After setting them up, you can configure them in SC.Shopping.Configuration.js, in particular the facets object. Here you configure individual facets using the available properties, as documented.

Before starting, you should read all related documentation.

Further Reading