Using the Hierarchical Refiner in PnP Modern Search: Tips and Tricks and the limitations you should know

TL;DR

This post explains how to use the Hierarchical Refiner effectively—and where limitations in the Microsoft Search APIs require creative design choices.

Understanding the Hierarchical Refiner

The Hierarchical Refiner displays search filters in a tree-like structure, reflecting the hierarchy of taxonomy terms. This allows users to drill down through categories and subcategories, making it easier to find relevant content.

Why use a hierarchical approach?

Unlike flat refiners that return a simple list of values, a hierarchical approach groups related terms together, improving both navigation and usability.

For example, in an policy library tagged with which geographic location the content is valid for, users can expand regions, contries and even down to city or specific location level.

Note: Depending on your configuration, nodes and branches can still appear even if the current dataset does not contain matching items.

Key features

• Supports multi-level taxonomy structures

• Displays parent/child relationships in a collapsible tree

• Allows selection of single nodes or entire branches

• Works with both Microsoft Search and SharePoint Search

  
  

How to set up a Hierarchical Refiner

1. Map your managed metadata correctly - Ensure your RefinableString is mapped to the TAXID crawled property.

   
   

   

2. Add the property to your query - Include the RefinableString in Selected Properties in the Results web part.

3. Configure the refiner

   • Add a refiner in the Filters web part

   • Select Hierarchical layout

   • Configure it in the settings panel

     
     

     

Yes, the configuration UI isn’t pretty—but it does the job and I have no frontend skills whatsoever.

Important configuration tips

• Set “# of values” = 1000 (more on this later)

• Consider enabling:

  • Expand all nodes by default

  • Hide nodes not present in the current dataset (useful if many unused terms)

• Enable caching (e.g. 3 days) to improve performance

  Still a relatively new feature—monitor for any side effects

• 
  

How it behaves

Once configured:

• The refiner shows taxonomy terms (either all or filtered based on your settings)

• Selecting a node filters results:

  • Direct matches

  • Or all items under that node (child terms included)

👉 In short: proper hierarchical filtering, finally.

Known limitations

1. Performance on large term sets

Large taxonomies can slow things down:

• The refiner must load and build the hierarchy dynamically

• Thousands of terms = noticeable load time

  
  

2. The 1000-value limit

Microsoft/SharePoint Search enforces a hard limit of 1000 refiner values.

This means:

• Only the first 1000 terms are returned

• Larger term sets will appear incomplete

• Users may miss values entirely

• 
  

Best practices for large datasets

Limit the scope

Reduce what the refiner needs to process:

• Pre-filter by:

  • Content type

  • Site or hub

  • Department or project

• Avoid tenant-wide queries

• 
  

Design your taxonomy wisely

• Avoid massive term sets

• Split large sets into smaller, logical groups

  
  

Use verticals

Segment your content:

• By department

• By project type

• By content category

👉 Smaller datasets = faster refiners + fewer missing values

Tune refiner settings

Optimize for your scenario:

• Max values (up to 1000)

• Sorting (alphabetical vs count)

• Disable counts if performance is critical

  
  

Pre-filter via query

Reduce the dataset before it hits the refiner:

• Date ranges

• Content type

• Author or metadata filters

  
  

Example scenario

Scenario:A document library with 50,000 documents and a “Projects” taxonomy containing 1,200 terms.

Problem

• Only part of the taxonomy is shown (due to 1000 limit)

• Users miss projects in the refiner

• Page load is slow

Solution

1. Apply pre-filters - Filter by department first

2. Use verticals - Split views by department or project type

3. Split the taxonomy - Replace one large term set with smaller ones

4. Validate performance - Confirm faster load times and full term visibility

   
   

Summary

The Hierarchical Refiner is a powerful way to bring structure and usability to search experiences built on managed metadata.

However, to make it scale, you must:

• Control dataset size

• Design your taxonomy carefully

• Work within the 1000-value limit

Feedback

Please share feedback via the GitHub repository:

• Issues → bugs and problems

• Discussions → ideas and questions