Search Filters Web Part¶

The 'Filters' Web Part allows to filter the current results displayed in a 'Search Results' Web Part. This component is higly configurable to meet you requirements and it works for all data sources.

Configuration¶

Connection¶

To use the filters, we must first connect it to one or multiple 'Search Results' Web Parts. In the other hand, you must connect back those Web Parts to the 'Filters' one. It is a two-ways connection.

If you connect more than one Web Part, the filter values and counts will be merged for similar filter names:

Example

Data sources #1 and #1 expose respectively a 'FileType' filter with values and counts value1:1, value2:1 for #1 and value2:1, value4:1 for #2 and both are connected to the filters Web Part. In this case, a single 'FileType' filter name will be displayed (because the filter name is the same) with values value1:1,value2:2,value3:1,value4:1. If you select a value that is not present in a data source (ex: value1 for data source #2), you will simply get zero result.

Filter settings¶

The filter settings are as follow:

Setting	Description
Display Name	A friendly name for the filter
Filter field	The internal data source field to use as filter. Here you can select a field from the current data source (if data have been already retrieved) of type your own custom value (press enter to validate).
# of values	The maximum number of values to retrieve for a filter, up to 1000. When left unset, SharePoint Search defaults to 100 and Microsoft Search to 10. The field shows the default as a hint when all connected results sources have the same known default; it does not save that hint as a configured limit. Enter a number to override the default.
Show warning when limit is reached	Off by default. When enabled, an info icon appears after the filter title if the connected API returns a number of refiner or aggregation values equal to or greater than the configured # of values limit. Hover the icon to see the warning details.
Template	The template to use to display filter values. The builtin templates are: Check box Date range Date interval Combo You can search a value directly in the list by typing keywords in the combo text field. People Template (a refiner for people values) People Picker (searchable picker for tenant users) Hierarchical Refiner (taxonomy tree for parent/child terms)
Allowed email domains	Optional restriction for the People Picker template. Select the Domains (n) button to open a dialog where you add or remove email domains; leave the list empty to allow all suggestions.
Expand by default	If applicable for the selected template, display values as expanded.
Show count	If applicable for the selected template, display counts for values.
Mutli values	If applicable for the selected template, allow selection of multiple values.
Operator between values	If multi values is selected, the operator to use between values (OR/AND).
Sort values by	Sort values by name or by count.
Sort direction	Sort values in ascending/descending order.

Restricting the People Picker by email domain¶

For a filter using the People Picker template, select the Domains (n) button in the Allowed email domains column. The dialog lists the allowed domains; enter a domain such as contoso.com (or several, separated by semicolons or commas) and select Add, or use the remove button next to a domain. Select Save to apply the changes, including any valid domains still in the input, or Cancel to discard them. The button is disabled for other templates. The domains are stored as a semicolon-separated string, so existing configurations continue to work. This option applies to that filter only; it does not affect the separate People Template refiner. Leave the list empty to retain the unrestricted picker.

Matching ignores case and requires an exact domain. For example, contoso.com permits person@contoso.com but not person@subsidiary.contoso.com; add the subdomain explicitly if needed. Enter domains without @, wildcards, URLs, or IP addresses. The picker excludes suggestions without a usable email-like address, including encoded guest logins. The underlying picker may provide an email-like login when an email address is unavailable, so the domain is not proof of mailbox ownership. Invalid domain settings are reported and disable the picker until corrected; the dialog highlights invalid stored entries and blocks saving until they are removed.

Previously saved selections may contain only a display name instead of an email address. When the domain cannot be verified, the selection is kept and a warning is shown; the selection can be removed with its remove button. Selections with a known disallowed domain are removed. A saved display name can be shared by multiple people, so an ambiguous submitted value may remain until the user clears or reapplies the filter.

The allowlist filters the picker UI, not access to content or a security boundary. The People picker applies this restriction after its service has limited the number of returned suggestions, so fewer matches may appear even when other matching users exist.

If you use a custom filters layout based on an older built-in template, add these attributes to its static pnp-peoplefilter element:

data-allowed-email-domains="{{filter.allowedEmailDomains}}"
data-domain-selection-removed="{{filter.domainSelectionRemoved}}"

Exact text refiner matching¶

For SharePoint Search, selected text refiner values retain the original refinement tokens returned by SharePoint, including tokens containing accented characters. These tokens are sent in RefinementFilters using FQL syntax rather than converted into plain-text search expressions. This keeps selecting a value such as Contoso from also matching a different refiner value such as Not Contoso.

Multiple selected values continue to use the configured Operator between values (OR/AND). Date ranges, Yes/No filters, and hierarchical taxonomy selections retain their existing handling. Custom filters that supply literal text instead of SharePoint refinement tokens are not automatically converted into exact-match tokens.

Refiner value limit warning¶

Use Show warning when limit is reached together with # of values when a filter can return many refiner or aggregation values.

When the warning is enabled, an info icon is shown next to the filter title if the connected API reports that the configured # of values limit was reached. This means the visible filter list may be truncated and not all matching values are currently shown.

For troubleshooting, PnP Modern Search also writes a browser console message for each refiner or aggregation showing how many values were returned by the API and what limit was configured. When the returned count matches or exceeds the configured limit, the message is emitted as a warning and notes that additional values may have been truncated by the API.

Example console warning:

[PnP Modern Search][SharePoint Search] Refiner 'RefinableString00' returned 500 item(s), matching or exceeding the configured limit of 500. Additional values may have been truncated by the API.

This is useful when:

you keep # of values lower than 1000 for performance or readability
you want to warn users that they should narrow their search before trusting the full filter list
you need a visible hint that increasing # of values may expose more refiner values

Hierarchical refiner (taxonomy)¶

Use the Hierarchical Refiner template when you want to browse and filter terms as a tree (parent/child hierarchy).

This template is designed for taxonomy-backed fields (typically RefinableStringXX values returned by search refiners).

Hierarchical settings¶

When the Hierarchical Refiner template is selected, a Hierarchical Settings entry appears in the filter row.

Setting	Description
Term Set	Select the term set used to build the tree. Term sets are grouped by term group, and you can search within available term sets.
Cache Duration	Number of days to cache retrieved terms (1-5 days, default 3).
Hide nodes not in the current data set	Removes branches that do not contain any values returned in the current result set. This option is useful when many terms are never or rarely used, making large parts of the tree irrelevant.
Expand all nodes by default	Expands the full taxonomy tree when the filter loads. This is different from the general Expand by default option, which only expands the root level.
Refresh Cache Now	Clears the cached terms for the selected term set. The terms are fetched again the next time the hierarchical tree is loaded.

Option behavior with hierarchical template¶

General filter option	Behavior with Hierarchical Refiner
Expand by default	Supported. Expands only the root level of the hierarchy.
Show count	Not shown in the hierarchical tree UI.
Multi values	The hierarchical tree behaves as single-select in the UI. Only one active selection is kept at a time, even though this general option still exists in the filter configuration.
Operator between values	Not relevant in practice because hierarchical selection is single-select.
Sort values by / Sort direction	Disabled for this template. The hierarchy follows term store structure.

Localization and deep links¶

Works with localized taxonomy refiner values when Enable localization is enabled in the connected SharePoint Search data source.
The limit warning info icon tooltip is localized using the current UI language for all supported Search Filters languages.
Deep links generated from hierarchical selections are supported.
Leaf selections preserve the original encoded SharePoint refinement token. Older deep links containing decoded, label-bearing L0 values are restored as label-independent exact-term GP0 tokens.

Selection behavior¶

Selecting a parent node applies a taxonomy parent token so the selection includes child terms.
Selecting a leaf node applies that specific term only.
If the search response does not contain a matching leaf refiner bucket, the fallback exact-term token preserves the term GUID's hyphens.
When a hierarchical value is already selected, the component automatically expands the selected branch so users can see the current context.

Filter styling¶

The filter styling section allows you to customize the visual appearance of the filter panel to match your branding and design requirements.

Setting	Description	Default value
Filter background color	The background color of the filter panel.	Transparent
Filter border color	The border color of the filter panel.	Theme primary color
Filter border thickness	The thickness of the filter panel borders (in pixels).	1px
Reset styling to default	Reset all styling options to their default values.	N/A

Web part title styling¶

The title styling section allows you to customize the visual appearance of the web part title.

Setting	Description	Default value
Title font	The font family to use for the web part title.	Segoe UI
Title font size	Controls the font size (in pixels) for the web part title.	16px
Title font color	The color of the web part title text.	Theme primary color
Reset title styling to default	Reset all title styling options to their default values.	N/A

Clear all filters¶

The Show "Clear all" button toggle is on page 2 of the property pane, below Web part title styling. When enabled, a right-aligned Clear all action appears beside the Search Filters web part title. It is disabled when no filters are applied or while results are updating. Selecting it clears all applied filters, updates connected results, and removes the filter deep-link query parameter. The feature is disabled by default.

The busy cursor and Clear all action follow the loading state of the connected Search Results web parts, even when the returned refiner values do not change. With multiple connected results web parts, the filters remain busy until all have finished loading.

Operator between filters¶

You can select the operator to use between filters (OR or AND).

Filter types: 'Static' filter versus 'Refiner' filter¶

The Web Part supports two types of filters ('Static' and 'Refiner'). However, there are some differences that are important to understand between these two if you want to use them properly:

Refiner: a 'Refiner' filter means the filter gets its values from the data source and sends back the selected ones the data source. If the data source has no result, there won't be any refiner values, simple as that.
Static filter: a 'Static' filter means the filter doesn't care about filter values sent by the data source and provides its own arbitrary values regardless of input values. A date range picker (or any picker) are good examples of what an 'Static' filter is. Such a filter do not need necessarily need a Search Results connection.

Use indexed property bag properties with taxonomy values¶

This behavior only works with the SharePoint Search Data source and the Enabled localization flag activated.

Using an indexed property bag value could be useful to store information about a SharePoint site or other element that can't be tagged with a taxonomy value directly. The PnP Modern Search solution supports property bag properties values that use the following taxonomy value format to be able to filter on them (ex: a taxonomy multi values separated by a semicolon (;)):

These taxonomy values can then be used in the Filters Web Part using a RefinableStringXX search managed property to filter specific sites or elements. As an example, you can refer to the "Create an end-to-end Office 365 groups provisioning solution" tutorial GitHub project to leverage this format.

Filter deep linking¶

The Search Filter Web Part supports deep linking, meaning you can preselect filters from the URL at page load. When filter values are selected, a query string parameter named f_<instanceId> is appended to the current URL containing the current filter values data. This instance-specific parameter name avoids conflicts when multiple Search Filters web parts are present on the same page.

If you have connected the search result web part to a search box, ensure the search term is set to be dynamic and part of the URL in the search box web part. If not, copying the URL will not contain the search terms."

If you need to build those links yourself in a custom results template, you can use the built-in stringToHex helper documented in the templating helpers documentation.

Important

We recommend to use the URL generated from filter values selection instead of crafting the URL manually.

Audience Targeting¶

You can control the visibility of the filter web part based on user group membership. See Audience Targeting for details.