PnP Modern Search is an open source solution that provides an easy-to-use and customizable search experience in SharePoint Online. PnP Modern Search offers a range of features, such as faceted search, query suggestions, and search refiners, to help users refine their search results and find the information they need more efficiently. In this post, we will explore how to create custom PnP Modern Search pages to suit your organization’s needs.
It is important to note that in most cases, we don’t use PnP Modern Search to replace Microsoft Search, but rather to augment it. Augmenting Microsoft Search with PnP Modern Search can provide a more comprehensive and personalized search experience, especially when the requirements is to create a tailored search applications.
It is always important to carefully evaluate your organization’s search needs and consider the benefits of integrating PnP Modern Search into your existing search environment.
Deploy PnP Modern Search Web Parts
Download the PnP Modern Search Package
The first step is to deploy the PnP package to your tenant.
You can download the latest releases HERE.
You’ll see there are two major versions: version 3 and version 4. Important notes:
-
- Version 4 uses a brand new code architecture and replaces the older version 3 codebase. Although v3.x will not receive any new features, bug fixes, and other necessary updates will continue to be provided as needed.
-
- Because version 4 is not at feature parity yet with version 3, you can still use the v3.x packages to meet your requirements.
-
- Unfortunately, there is no automatic upgrade route from v3.x to version 4 because of the new architecture.
-
- The new Microsoft Graph Search API search functionality will be only available in version 4.
If this is the first time you install PnP Modern Search, always go for version 4.
On the Releases page, scroll down to Assets, and then click on the .sppkg file:
Deploy the PnP Modern Search package to your tenant’s App Catalog
App Catalog is a special site collection in SharePoint, that stores the apps for your organization’ use. If you have an existing App Catalog, you can jump right to deploying the PnP Modern Search package there. Otherwise, you have to create a new App Catalog.
Create a new SharePoint App Catalog
You have to be a tenant administrator to create a new App Catalog.
Go to Microsoft 365 Admin / SharePoint Admin Center. On the left menu, click on “More features”, and select “Apps”:
Once there, click on New App Catalog, then fill in the form, so that the new site collection will be created:
Deploy the PnP Modern Search Package
Once your App Catalog is ready (or you have one that was created earlier), open its URL and then click on “Apps for SharePoint”:
On this screen, click on Upload, then choose the PnP Modern Search package file that you downloaded previously.
When prompted to trust the PnP Modern Search Web Parts package, tick off the checkbox if you want it deployed across all site collections. If you only need to deploy on a few chosen sites, leave unchecked. Then click Deploy:
Once done, you should see the PnP Modern Search Web Parts in the App Catalog:
Note: The first, 2021 Jan release of version 4 required two separate packages, due to the extensibility library being an individual .sppkg file. However, the March 2021 release has made this process much simpler by replacing that dependency with a single npm package. Since then, when deploying your SPFx solution into the app catalog, you'll only need one package.
Note: If you have PnP Modern Search version 3 deployed on your tenant, this blog post will help you decide if you should consider switching to version 4.
Set up Your First PnP Search Page
Pages with PnP Search Web Parts can be added to any modern site. My recommendation is always try this out on a test site first, before deploying to production.
Add the PnP Search Web Parts to your Page
First, open your page to edit. In the web parts list, search for “PnP”, and you’ll see the PnP Modern Search Web Parts there.
The package contains the following web parts:
-
- PnP Search Box
-
- PnP Search Filters
-
- PnP Search Results
-
- PnP Search Verticals
To get started, we need at least two web parts: a search box and a search results web part.
Search Box Web Part
The Search Box web part can be added to the page by choosing “PnP Search Box” web part. At this point, you don’t have to do any further configuration.
Search Results Web Part
The next step is to add a PnP Search Results web part to the page. Then, you have to connect it to the Search Box web part by following these steps:
-
- Edit the page.
-
- Edit the properties of the Search Results web part.
-
- Switch to page “3 of 4” on the web part properties.
-
- Turn on “Use input query text”.
-
- Select “Dynamic value” in the radio button list.
-
- Select “PnP – Search Box” in the “Connect to source” dropdown.
-
- Select “Search query” in the “PnP – Search Box’s properties” dropdown.
Once done, save the page and enjoy your very first PnP search page!
Additional Query Conditions
You might want to limit the scope of search to one or more specific sites, or to display specific types of documents, or to filter by date, etc.
You can easily do it by using KQL in the PnP Search Box settings.
For example, if you want to display documents only, but exclude pages from a specific site, you can use this search query in the Query Template:
{searchTerms} IsDocument:1 -fileextension:aspx
-Path:"https://yourtenant.sharepoint.com/sites/yoursite*"
Note: {searchTerms} refers to the query terms which the PnP Search Result web part receives from the Search Box, as configured above.
Search Filters web part
Once your page is ready with the search box and search results web parts, the next step is to add some filters to the page:
Add the PnP Modern Search Filter Web Part to your page
To add search filters to your page, edit the page, and click on “Add a new web part”. Search for PnP, and select “PnP Search Filters” from the list.
To make the Filters web part work, we need to define to connections:
-
- The Filters web part needs to receive the result set from the Search Results web part, so that it ca reflect the actual results (and their item counts) on the filters.
-
- The Filters web part needs to send the filtering criteria to the Search Results web part.
Connect the Filter web part to the Search Results web part
First, let’s connect the Filters web part to the Search Results web part.
To do this, open the Filters web part with the Configure button, or “Edit web part”. On the first page, open the “Use data from these web parts” drop down, and select the Search Results web part – so that the filters web part can receive the result set from it.
Note: You can connect the Filters web part to multiple Search Results Web Parts.
With this, your Filters web part now receives information about results, and it’ll use this to display the corresponding filters.
Connect the Search Results web pat to the Filter web part
The next step is to configure the Search Results web part to receive the selected filter values from the Filters web part.
Edit your page, select the Search Results web part, and edit it. The web part has many settings and properties, now let’s focus on the Filters settings only. Turn to page 3, and then look for the radio button “Connect to a Filters web part“:
Customize the Filter web part
Of course, you can also select other Refinable Managed Properties to be used as filters.
Edit the Filters web part, and click on “Customize Filters”:
On this page, you will be able to add, remove, and edit the filters (refiners):
You can apply the following settings to each filter (refiner):
-
- Display Name: The label which will be displayed on the UI.
-
- Filter field: The name of the refinable managed property to be used.
-
- # of values: How many filter values you want to be displayed.
-
- Template: What refiner template to be used (how to display the filter values): check box, date range, date interval, combo box)
-
- Expand by default: If set, the refiner will be expanded by default. Otherwise, it’s collapsed.
-
- Show count: If set, the item count will be displayed for each filter value.
-
- Multi values: If set, the user can select multiple values from the same filter.
-
- Operator between values: If the refiner is multi-value, you can define if the operator should be OR or AND between these values.
-
- Sort values by: The values can be sort by name or by count.
- Sort direction: Ascending or descending.
