Azure / Office 365 / SharePoint Development / Search

Filtering results on predefined set of values in your display template

March 09, 2015

For one of my clients I investigated the possibility to include result filtering or refinement into a display template for the Content Search Web Part. The reason to include this filtering functionality into a display template is to make it easier to fit into the corporate design. Another reason is to minimum the amount of display templates that get loaded on your page.

The first thoughts that could pop up in your mind would be to approach it by adding a Refinement and Content Search web part on the page. The advantage by making use of the refinement web part is that you do not have to worry about the refinement values because they are automatically retrieved by the web part. The downside is that this web part requires two additional display templates that get loaded on your page, and it also makes the design process a bit more difficult.

How it works

As I mentioned in the title of this article, the filtering of the search result is done by a predefined set of refinement values. In my display template these values are displayed as a link for each type of content. This allows the user to quickly filter the results for a specific type. Example: showing news category links in order to let the user filter the news based on his preference.

Start by creating a new control display template and add a link to the control display template like this:

In the link element an onclick attribute is specified with a function call. Once you click on the link, the function executes a refinement query with the filter value that you clicked. In order to make it work, you need to add the following code block inside a script element in your template:

In the code above you can find two functions: click and checkRefinement. In the click function a new QueryState object is created in which the selected refinement value gets defined. The checkRefinement function is required to see if there is already another refinement in place.

At the moment the template output looks like this:

Display template with filter links

Display template with filter links


When clicking on the Refine on 'docx' link you only retrieve docx documents.

Search results filtered on docx file extension

Search results filtered on docx file extension


The thing that remains is a link that allows you to remove the current filter that is in place. As like in the first step, you need to add a new link and a function to the template.

The corresponding function:

In the all function the refinement gets removed by creating a new QueryState in which you do not specify any query parameters or properties. This QueryState triggers the web part to perform the original (query you specified in the query builder) search query.

All results link

All results link


Making the filtering values customizable

The downside of working with predefined values is that the template can only be used for one type of results. So if you want to use this template for a different kind of content, you need to copy the templates and do your changes in the copied version. This is not a preferred way of working.

In one of my previous articles, I explained how you can add configurable settings into your display template: Adding configurable settings to your display templates. You can apply that approach by adding two setting properties into your item display template that allow you to define the managed property name and the corresponding filter values. If you want to use the template for another kind of content, you just need to modify the display template setting properties in the web part.

Filter settings in the property mappings section

Filter settings in the property mappings section


You can find the final versions of the item and control template on GitHub: Result refinement display templates (CSWP).


  • Your blog is BY FAR the most helpful one out there when it comes to documenting how JavaScript can manipulate the SP 2013 experience. Thanks!

  • Koen Stoops

    Hoi Elio, I have tried implementing this, but in SharePoint online the suitserviceproxy.aspx is failing to proces the enlarged url

    • Can you give me a bit more details. Did you upload the control and item display templates to you master page gallery? Why kind of error are you retrieving?

      • Koen Stoops

        Hi Elio, it was just a javascript error on call to SuiteServiceProxy.aspx. The url went to large.

  • Melissa McElroy

    Hello –
    When I try to implement this code, I continue to receive the error Object doesn’t support property or method ‘join’. It’s being thrown in the CheckRefinement function. Any ideas?

    • Melissa, which template are you using? Do you have another error in the browser developer tools console?

      • Melissa McElroy

        I have tried Search Results Control (the real goal) as well as the Content Search List. Same error with both. No other errors.

        • If you used the Control_Refine.html file, you also need to be using the Item_Refine.html at the same time. Did you do this?

          Are you able to debug the template? I cannot reproduce it on any of my environments.

  • Walter Johnson

    How are you defining the variable Srch?

    • The Srch object should be available when using display templates. This gets automatically loaded with a CSWP or SRWP.

      • Walter Johnson

        Can you set the results of a SRWP with the results of a searchExecutor with Srch or ctx? For example:

        var results = searchExecutor.executeQuery(keywordQuery);

        on successful execution produces:


        but I want to set the results of the SRWP with these rows. Is this possible?

        • Never tried, but don’t think it’s a great idea to do so. What are you trying to achieve?

  • Peter Dotsenko

    Elio, awesome blog.

    I was wondering how would you control refining before rendering.

    Is there a way to modify Srch.U.fillKeywordQuery and particularly get_fallbackRefinementFilters before Srch.U.fillKeywordQuery executes?

    Example, i have a localStorage value ie “Washington”. I would like CSWP to refine based on that localStorage value on initial load.


  • Pingback: SharePoint 2013 Search Info – Kathryn Birstein's Blog()

  • Andre Terbrack

    Hello Elio,

    thx so far for the great work.

    With this template i have some problems.
    Sometimes it says that click is “undefined”. I did a test on two different SharePoint Farms.

    Do you have an idea why?

    My goal is not to refine. I would like to do a diffent search query when i click a link.
    But here I also have Problems:

    My idea was to use the below code instead for the queryState. But the Webpart did not update.

    var queryState = new Srch.QueryState();
    queryState.k = “”;
    queryState.r = [];
    var queryStateArgs = new Srch.QueryEventArgs(queryState);

    Thx in advance.



    • Thank you for mentioning. This will have something to do with the clean-up I did a couple of months ago. I have updated the templates on GitHub, so they should work again.

      • Andre Terbrack

        ok, thanks the refinement works again. :).

        I wanted to change the code to do a new search query.
        queryState.k = “test”;
        I changed the query state but nothing happens in this webpart.

        Any Ideas?



        • Have you checked the search API call? You can check these out via the network tab of the browser developer tools.