
Last updated: April 14, 2021
If you use Microsoft 365 (Office 365), you probably have been using Microsoft Search, too. But there might be use cases, when it’s not enough – for example, when you need a customized Search Application. If this is the case, your number one option might be to deploy PnP Modern Search Web Parts. This is an open source solution that helps you to build customized search applications in SharePoint Online modern experience.
However, this solution has to be deployed manually to your tenant. Let’s see how.
1 – Download the PnP package
You can download the latest releases HERE.
You’ll see there are two major versions: v3 and v4. Important notes:
- The v4 version uses a brand new code architecture and replaces the older v3 codebase. There will be no new features added to v3.x anymore, but bug fixes will be provided as needed.
- Because v4.x is not at feature parity yet with v3.x, you can still use the v3.x packages to meet your requirements.
- Also, there is not an auto-upgrade path from v3 to v4 due to the new architecture.
- New search functionality backed by the Microsoft Graph Search API will be v4 only.
If this is the first time you install PnP Modern Search, always go for v4.
On the Releases page, scroll down to Assets, and then click on the .sppkg file:

Note: If you’ve installed the 2021 Jan release of v4, you had to deploy two packages, because the extensibility library was a separate .sppkg file. With the 2021 March release, there’s only one package, the team has replaced the extensibility library dependency by an npm package. Now you only need to deploy one SPFx solution in you app catalog.
2 – 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 deploy the PnP Modern Search package there. Otherwise, you have to create a new App Catalog.

2.1 – Create a new 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 the select “Apps”:

Once here, click on New App Catalog, then fill in the form, so that the new site collection will be created:

2.2 – Deploy the PnP Modern Search Package
Once your App Catalog is done, or you have one that has been 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 which you downloaded in Step 1.

When you’re asked if you trust PnP Modern Search Web Parts, click the checkbox if you want to deploy it to all site collections, otherwise leave it unchecked if you need it on a few selected sites only. Then click Deploy:

Once done, you should see the PnP Modern Search Web Parts in the App Catalog:

3 – Enjoy!
Now, go to any (modern) site on your tenant (in a site collection where you’ve deployed PnP Modern Search above), and edit the page. In the web parts list, search for “PnP”, and you’ll see the PnP Modern Search Web Parts there:

What’s Next?
In the next part in this series, I’ll demonstrate how to use the PnP Modern Search Web Parts in SharePoint Online, and also when and why you might need them.
Meanwhile, if you don’t mind, please share in the comments what you miss from out-of-the-box Microsoft Search.
Hi Agnes
How do I download the latest bug fixed version 3? All links take me to Version 4
Thanks
Hi Pauline,
You can go to https://github.com/microsoft-search/pnp-modern-search/releases/, and scroll down to the v3 releases.
-Agnes
Hello Agnes, one question regarding filters/refiners in a multinlingual environment. What is your strategy for content types if you want users see the content type name in their default language in the refiner? I’m currently using SPContentType managed property but it does not support translation like managed metadata properties.
Thanks.
I’m having trouble with the web parts. I have two tenants (one of which I am global admin).
I’ve installed the package in the tenant site collection for one tenant but don’t have the access to install at the tenant level in the other.
I added a search box from the site collection app catalogue but don’t get results (I’m directing to new page with a search results web part). Every time I edit the results page, I lose the option for ‘q’ and only get ‘Mode’ in the parameters properties.
This problem doesn’t happen with the web parts installed in the tenant app catalogue.
Are there limitations when using a site collection app catalogue?
Did you try to remove the web part(s) from the page and then add again?
Excellent article. Nice and easy to follow.
Many thanks.
So clearly written and so easy to use !! Keep up the good job 🙂