Understanding Refinement Web Part on SharePoint 2013 Online (Office 365)

In SharePoint 2013, a new search web part named Refinement was introduced, which helps in narrowing down the search results.

Refiners are based on managed properties from the search index.

To use managed properties as refiners, the managed properties must be enabled as refiners, or crawled properties must be mapped to managed properties that are enabled as refiners.




Understanding Refinement Web Part

By default Search Center in SharePoint 2013 is composed of four main web parts:



As we know, Refinement Web Part is intended to filter information displayed in Search Results Web Part.

For us, as a Developers, we are interested on how we can modify the default behaviour of these web parts.

So, if we take a look the Web Part XML Definition of Refinement WebPart:

<webPart xmlns=“”>
<type name=“Microsoft.Office.Server.Search.WebControls.RefinementScriptWebPart, Microsoft.Office.Server.Search, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c” />
<importErrorMessage>Cannot import this Web Part.</importErrorMessage>
<property name=“HelpUrl” type=“string” />
<property name=“UseManagedNavigationRefiners” type=“bool”>False</property>
<property name=“TitleUrl” type=“string” />
<property name=“Hidden” type=“bool”>False</property>
<property name=“ChromeType” type=“chrometype”>TitleOnly</property>
<property name=“AllowClose” type=“bool”>True</property>
<property name=“TitleIconImageUrl” type=“string” />
<property name=“AllowMinimize” type=“bool”>True</property>
<property name=“AllowEdit” type=“bool”>True</property>
<property name=“Direction” type=“direction”>NotSet</property>
<property name=“Height” type=“string” />
<property name=“AllowConnect” type=“bool”>True</property>
<property name=“MissingAssembly” type=“string”>Cannot import this Web Part.</property>
<property name=“AllowHide” type=“bool”>True</property>
<property name=“Description” type=“string”>This webpart helps the users to refine search results</property>
<property name=“StatesJson” type=“string”>{}</property>
<property name=“QueryGroupName” type=“string”>Default</property>
<property name=“ChromeState” type=“chromestate”>Normal</property>
<property name=“ExportMode” type=“exportmode”>All</property>
<property name=“AllowZoneChange” type=“bool”>True</property>
<property name=“RenderTemplateId” type=“string”>~sitecollection/_catalogs/masterpage/Display Templates/Filters/Control_Refinement.js</property>
          <property name=“CatalogIconImageUrl” type=“string” />
<property name=“EmitStyleReference” type=“bool”>True</property>
<property name=“HelpMode” type=“helpmode”>Modeless</property>
<property name=“Title” type=“string”>Filter By:</property>
<property name=“AlternateErrorMessage” type=“string” null=“true” />
<property name=“Width” type=“string” />
<property name=“EmptyMessage” type=“string” />
<property name=“ServerIncludeScriptsJson” type=“string”>null</property>
    <property name=“SelectedRefinementControlsJson” type=“string”>{“refinerConfigurations”:[{“propertyName”:“RefinableString06”,“type”:“Text”,“sortOrder”:0,
“displayTemplate”:“~sitecollection/_catalogs/masterpage/Display Templates/Filters/Custom_Filter_MultiValue.js”,“sortBy”:0,




We can see two important properties for us:

RenderTemplateId: That is the Control Display Template for all the Refinement. If we need to change some common UI element, or functionality using JavaScript we can provide a Custom js file. More information here:

SelectedRefinementControlsJson: It is a JSON-based property intended to configure declaratively all the refinement properties.

  "refinerConfigurations": [
      "propertyName": "RefinableString06",
      "type": "Text",
      "sortOrder": 0,
      "displayTemplate": "~sitecollection/_catalogs/masterpage/Display Templates/Filters/Custom_Filter_MultiValue.js",
      "sortBy": 0,
      "maxNumberRefinementOptions": 15,
      "displayName": "Topics",
      "useDefaultDateIntervals": false,
      "aliases": null,
      "refinerSpecStringOverride": "",
      "intervals": null

displaytemplate attribute is where we could configure custom refiner display template that was prevoiusly uploaded to “_catalogs/masterpage/Display Templates/Filters


Connection between Refinement and Search Results Web Parts

In order to provide custom features for Refinement WebPart in Office 365 and SharePoint 2013, it is important to understand completely how Refinement Web Part and Search Result Web Part are interconnected, but let’s focus on this post at the connection between Refinement and Search Results Web Parts.

If we edit Refinement Web Part, we can see the Property “Refinement Target” that is linked directly to Search Results web part, which means this refiner panel is sending information directly to this Results Web Part.


Behind Scenes, the search web parts make use of a JSON formatted string in the URL to do the search and refinements. Also, these two webparts are interconnected by SharePoint OOTB JavaScript engine.





You can see an extended explanation about Search.clientcontrols.js here:

You can see some examples about URL Query String (hash) usage in Paul Ryan blog:






One Thought on “Understanding Refinement Web Part on SharePoint 2013 Online (Office 365)

  1. wow excellent post really it is helpful blog.

Leave a Reply

Your email address will not be published.

Time limit is exhausted. Please reload CAPTCHA.

Post Navigation