Azure / Office 365 / SharePoint Development / Search

Sharing my managed metadata refiner display template

March 17, 2017

Do you have a refiner template that shows the refiners based on the hierarchy of a term set, or can you explain how to build it?

These are probably two of the most asked questions I received the last couple of months/years. Back in 2015 I created such a template, but never shared it until today.

The template that is shared renders the following output:

Refiner output example

Refiner output example

This corresponds to the exact same hierarchy of the term set:

Term set hierarchy

Term set hierarchy

The template only applies a simple styling to indent the children but does nothing more. If you want, you are free to style it to your needs.

Where can you find the template?

The managed metadata template can be found in the SPCSR GitHub repository: Managed metadata refiner.

Things you need to know about the template

There are a couple of things you need to know before you can start using this template.

  1. You will find two three templates in the repository. One for working with the term label value, one to work with the taxId value and one with which you are able to also filter on the parent terms. By default, SharePoint provides you the taxId managed property. But if you follow the best practices for working with managed properties in combination with managed metadata it could be that you configured it to use the label instead. Be sure to pick the right one.
  2. The template requires you to specify the term store ID. This is required for the template to retrieve all the terms from the term set. This is all explained on GitHub, so be sure to go through the configuration steps before uploading the template to your environment.



I just added a third template with which you can refine based on the parent terms. Here is an example:

Parent terms are refinable

Parent terms are refinable

If you compare this one, to the first image at the top. You will notice that Europe is now refinable. When you click on it, it will return all its children, so this allows you to go deeper into the hierarchy.


  • Danielle Collenbusch

    Hello thanks for sharing this information. Unfortunately my Refiner WebPart is empty after applying this control templates. I am using the label version. Do you know how I can figure out what is going wrong here? thank you!

  • Andy Speer

    Elio, Let me start by thanking you for your awesome work. The refiner template works perfectly in the Refinement Configuration -> Preview Refiners screen, but when I select OK on the Refinement Configuration, the refinement does not show up on the search page. Do you have any suggestions?

    • Are you able to debug the template? If so, can you check if you receive any terms from the term set?

      • Andy Speer

        Thanks for your help,

        The preview of the display template works perfectly from the “Choose Refiners” button in the web part properties dialog. When the page is rendered, we are getting div with an id of “EmptyContainer” for the actual refiner.

        I attempted to chase this down and I think it is coming from the script (in the Filter_ManagedMetadata_TaxID_parent.html) around line 220. The line is:

        if (hasControl) {
        if($isNull(refs) || $isEmptyArray(refs)) {

        I am having trouble understanding why it would work in preview, but apparently refs is null or empty when rendered on the page.

        • What you could do is set a breakpoint on this line:

          if (hasControl && !$isNull(listData)) {

          and check the contents of the listData object. This should contain the term values.

          Also check the type of data you are retrieving from the refiner. For this refiner template to work, you need to make use of the taxId MP. This contains the GTSet and L0 IDs which are required to built the hierarchy.

        • Andy Speer

          Thanks for the pointers. I will definitely try.

  • Billy Riley

    Great template, Elio! Question on the Parent version. When I try to refine on the Parent it does show the children but does not include the Parent itself. I was not sure If I was missing something or it is only supposed to display the children.

    • I updated the template on GitHub to support this.

      • Billy Riley

        Works great! Thank you.

  • David Fast

    Is there a way to add a class to the refiner once a user clicks on it? For example, out of the box, a selected sharepoint refiner has “a class=ms-ref-filterSel” (a parent class), which allows me to style an active refiner. This allows me to highlight the refiner and add an “x” graphic next to it, making it clear that clicking on it again removes the refinement. I’m not experienced enough in javascript to know how to add that.

    • Yes, that is possible and it is already included. Right now when you click on the link, it gets a “selected” class assigned. Check line 162:

      So you can style the selected term with the following CSS in the filter_mm.css file:

      .term .selected {}
      • David Fast

        Thanks, Elio. I’m using the term label version of the refinement display template, which doesn’t include the “selected” class, but I was able to add it to the template based on your Parent taxID version. Thanks so much for your work for all that you’ve shared!

        I still can’t figure out why I can’t get the Parent taxID version working. I think I’m still confused about how Sharepoint maps crawled and managed properties when it comes to managed metadata.

        • For the taxId template, you need to be sure you use the Managed Property which contains the taxonomy ID instead of the label. Normally, if your field gets indexed by SharePoint it will automatically create a managed property for it mapped to the taxId, so you can use that one.