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.

  • Ingridvg

    I’m trying to get the label-version working (unfortunately not very experienced).
    I get no results at all, just the title and the down-arrow. I don’t get the EmptyContainer,

    I checked listData and Refs, and both contain data as expected. What else could I check?
    Thanks in advance for your help.

  • Could you check the property name that is used during refinement? Is that the correct managed property name used?

  • Dheepa Iyer

    Thaanks for this solutions!! The hierarchy of the refinement panel shows up fine, but selecting the parent is not bringing the children tagged items. My items are tagged in Parent1:child1 format. Will it work for columns which is set to show the full path?

    • Which template are you using? In you case you should be using the `Filter_ManagedMetadata_TaxID_parent.html` version.

      • Dheepa Iyer

        That one does not seem to display anything on the refiners.

        • What do you retrieve as Managed Metadata values? You should use the tax IDs instead of the labels. If you are retrieving labels, you will have to use another MM.

        • Dheepa Iyer

          You mean to specifiy the Ows_taxid column of the crawled property to a different managed property?

        • Dheepa Iyer

          That worked by making a managed property to ows_taxid column. However when i have the managed metadata field set to show the full path, it shows duplicate items in the refinement panel – it basically shows everything twice.

        • Great to hear!

  • Michael de Nijs

    Hi Elio, I am struggling with the TaxID_parent template. I am using the taxid which is mapped to a managed property. See below image.
    When I configure the refiner webpart I choose my managed property and select the template. When using the preview option to see if it is working, the refiner is working. See below image.

    But when I am saving the webpart and page the refiner stays empty.
    Probably I am missing something why it won’t work.
    Can you assist? Thank you!

    • 1. Do you get any results in the search results web part?
      2. Do you see any error in the browser developer console (f12)?

      • Michael de Nijs

        1. Yes I do
        2. Only 1 warning: window.webkitStorageInfo’ is deprecated. Please use ‘navigator.webkitTemporaryStorage’ or ‘navigator.webkitPersistentStorage’ instead.

        • 1. OK
          2. Not from the template :-)

          In that case you will have to check where it goes wrong inside the template. Probably something small, as it is working in the preview.

          What you can do is add a `debugger` statement on line 64 and 217 of the template. Upload the template, and refresh the page with your dev tools open. For line 217, check if listData is not an empty array. For line 64, check that you get the term labels.

        • Michael de Nijs

          The listdata is not empty.

          I cannot get information about line 64 the term labels.

        • listdata indeed looks good. So it looks like you cannot retrieve the MM terms. In that case, check if the Term Set ID is correct in the template.

        • Michael de Nijs

          It is OK to me.

          termStoreName = ”,
          termSetId = ‘f4154203-34e5-4ace-a430-90e82e9cf062’,
          containerId = ”,

        • Ok, looks good indeed, so it might be something goes wrong in the SP JSOM code.

          Comment line 50. Uncomment lines 45 and 47. Provide your term store name in the termStoreName property line 24.

        • Michael de Nijs

          Unfortunatly nothing :( I see that the refs var is empty

        • In that case check if there are MM RefinementValue in your listdata object starting with: GPP|

        • Michael de Nijs

          Only L0|

        • Ok, that might be the issue, you should get more, otherwise no hierarchy can be created. Can you map your ows_taxId_Afb… crawled property to on of the available RefinableString.. managed properties and test that one out?

        • Michael de Nijs

          And it works!! I had to uncomment line 50 and comment line 45 and 47 again but it works! Thanks for the support!

        • Great! So it was the Managed Property.