Configure PnP Search web parts in SharePoint: connect the search box, results, and search page

How can you configure the PnP Search Web part so that the search box, results page, and URL parameters work reliably together? For a functioning search page, three things must be correct: the right PnP Web part package must be deployed, the Search Results must receive the search text from the Search Box, and the Query Template must actually pass this search text to the SharePoint search.

The most common errors do not occur in the results layout, but in the data flow between the Web parts. A search box can appear to work without the entered term reaching the results list. Similarly, a Results Web part can be set up correctly, but fail to show hits due to a query that is too narrow, missing permissions, or an unconnected URL variable.

This guide shows how to configure the PnP Search Web part, build a search page step by step, and then test the configuration with different user accounts.

When you should configure a PnP Search web part

SharePoint's standard search is suitable for many general search scenarios. A custom search setup with PnP Modern Search becomes interesting mainly when you want to control and display results on a modern SharePoint page specifically.

Typical use cases are:

• a custom search page for an intranet or knowledge portal,
• a search that considers only specific sites, libraries, or content types,
• a results display with additional metadata,
• filtering by document type, organizational unit, or category,
• separate search areas via so-called Verticals,
• a search box on the home page that redirects to a central results page.

PnP Modern Search does not replace the SharePoint search index. The Results Web part sends a query to the selected data source and prepares the returned hits for display. Which content is found still depends on the search index, search schema, query, and user permissions.

Search results or search rollup?

In the Web part catalog, depending on the installed version, both PnP – Search Results and PnP – Search Rollup may appear. For an interactive search page with a Search Box, filters, or Verticals, you must use Search Results.

Search Rollup is intended for independent content queries, for example for the latest documents or news. This variant is loaded with a delay for better load performance, but it cannot be dynamically connected to a Search Box or a Filter Web part.

Prerequisites for the search page

Before building the actual page, check the package, permissions, and target architecture. This avoids the configuration failing later due to missing Web parts or unapproved features.

Technical prerequisites

• a modern SharePoint Online site,
• a modern SharePoint page for the search interface,
• a global tenant App Catalog or a site collection App Catalog,
• the SPFx package pnp-modern-search-parts-v4.sppkg,
• edit rights on the target page,
• Read permissions for later users on the search page and the searchable content.

The package can be deployed centrally for all sites or installed specifically in individual sites. The App Catalog deployment is described in the article Deploy PnP Search Webparts; this article focuses on page configuration after installation. For a controlled start, it is recommended to first use a test site. Only after a successful function test should the solution be used tenant-wide or in further production sites.

Required roles and permissions

Different rights are required for the individual steps:

• SharePoint Administrator: Deploy the package in the global App Catalog and, if necessary, grant the requested API permissions.
• Site Collection Administrator or Site Owner: Install the app in the site, if a tenant-wide deployment is not used.
• Page Editor: Add and configure the web parts.
• End User: Read permissions on the search page and on the content that should appear as hits.

The Microsoft Graph permissions requested by the package are not required for every search scenario. Therefore, a pure SharePoint search should initially be implemented with the actually required permissions. Additional permissions should only be approved when functions such as search in Microsoft Graph entities, person information, or other Microsoft Search data sources are used.

Data flow between search box and search results

A PnP search page consists technically of several separate components. The Search Box does not perform the search itself. It merely provides the entered search text. The Search Results web part takes this value and sends a query based on it to the configured data source.

The simplified data flow looks like this:

1. A user enters a term into the Search Box.
2. The Search Box publishes the search text as a dynamic value.
3. Search Results receives this value via a web part connection.
4. The search text is inserted into the Query Template at the location of {searchTerms}.
5. SharePoint search processes the resulting KQL query.
6. The web part formats and displays the returned hits.

If one of these steps is missing, the search box may react visibly, but the result list remains unchanged or empty.

Configure PnP Search web part: connect search box and results

For the first function test, the Search Box and Search Results should be set up on the same modern SharePoint page. This allows errors caused by redirects and URL parameters to be excluded initially.

1. Create search page

1. Create a new modern SharePoint page.
2. Assign a unique name, for example Suche.aspx.
3. Add the PnP – Search Box web part to the top of the page.
4. Add the PnP – Search Results web part directly below it.

Do not use Search Rollup for this setup, as this variant does not support a dynamic connection to the Search Box.

2. Select data source in search results

Open the settings of the Search Results web part and select SharePoint Search as the data source. For a simple test, the following basic settings are sufficient:

The Query Template {searchTerms} is critical for the basic test. If this token is missing, the term passed by the Search Box cannot be used in the query.

3. Dynamically connect input search text

1. In the Search Results Web part, open the Connections or Verbindungen section.
2. Enable the use of an input search text.
3. Select a dynamic value.
4. Select the Search Box on the same page as the source.
5. Select the search text provided by the Search Box as the property.
6. Apply the settings and publish the page.

The names of the dynamic properties may differ slightly between package versions. What matters is that you select the Search Box present on the page as the source, not the page environment.

4. Test the connection

Open the published page in a new browser window and search for a unique term that appears in a known document title.

Check the following:

• Is a new query triggered after submission?
• Does the result list change with a different search term?
• Is the expected document found?
• Does the result list disappear or update when the search field is cleared?

Only when this setup works should you add a redirect from another page.

Connect a search box on a home page to the results page

In many intranets, the Search Box is located on a home page, while the results are displayed on a dedicated search page. In this case, the search term must be transferred between the two pages.

A query string parameter is usually easier to test than a URL fragment. A typical target address looks like this:

/sites/intranet/SitePages/Suche.aspx?q=reisekosten

1. Configure the search box on the source page

1. Open the settings of the Search Box on the home page.
2. Enable Send the query to a new page.
3. Select the search page you created earlier as the target.
4. Use a query string parameter as the transfer method.
5. Specify a parameter name, for example, q.
6. Use {inputQueryText} for the input transformation.

The parameter name is freely selectable. However, it must be written exactly the same on the target page. The parameters q, query, and search are technically different values.

2. Connect the search box on the target page to the URL parameter

The Search Box on the results page should take the value from the URL. This keeps the search term visible in the input field after the redirect and allows it to be changed subsequently.

1. Open the connections of the Search Box on the results page.
2. Activate a dynamic default value or input value.
3. Select the page environment as the source.
4. Select the query string parameter q.
5. Save and publish the page.

The value read from the URL is now displayed in the Search Box. Since Search Results is already connected to this Search Box, the value is subsequently passed to the result list.

3. Test the complete workflow

Do not start the test directly on the results page, but on the original home page:

1. Enter a search term on the home page.
2. Submit the search.
3. Check the target address in the browser.
4. Verify that ?q=Suchbegriff is included.
5. Check whether the term appears in the search field on the target page.
6. Check whether matching results are loaded.
7. Change the term on the target page and search again.

This verifies both the redirection and the connection on the results page.

Important settings for query, placeholders, and URL

Distinguish between query text and query template

The value received via the Search Box is the Query Text. The Query Template determines how this value is incorporated into the actual search query.

A simple template is:

{searchTerms}

A search within a specific site only can be set up as follows:

{searchTerms} Path:"https://tenant.sharepoint.com/sites/wissen"

If only documents should be displayed, the query can be further restricted:

{searchTerms} IsDocument:1

Such restrictions should be added individually and tested after each change. An incorrect path specification or an unavailable managed property can otherwise create the impression that the web part connection is not functioning.

Determine behavior for an empty search field

For an empty Search Box, there are two sensible variants:

• Empty result list: Suitable for a classic search where content appears only after input.
• Predefined hits: Suitable for a combined search and overview page, for example, with current documents.

A dynamic input search text can be supplemented with a default value in the Search Results Webpart. As a default query, a general KQL query or a fixed restriction can be used depending on the desired content.

The behavior when clearing the search field should also be checked. If Reset query on clear is enabled, a new query is triggered when the search term is removed.

Formulate placeholders clearly

The placeholder should describe the search area. Examples include:

• Dokumente und Seiten durchsuchen
• In der Wissensdatenbank suchen
• Richtlinien, Vorlagen und Anleitungen suchen

A precise placeholder prevents false expectations if the query is intentionally restricted to specific content or sites.

Keep URL parameters consistent

Use the same parameter name for all entry points. If a Search Box sends q but the results page expects query, the page will open but the search term will not be adopted.

After changes, also check if:

• the path to the target page is still correct,
• the page has been moved or renamed,
• old links still point to a previous search page,
• multiple search pages use different parameter names.

Typical errors and their causes

The search box responds but results do not change

In this case, the error is usually in the connection to the Search Results Webpart.

Check:

• Was PnP – Search Results used instead of Search Rollup?
• Is a dynamic input search text enabled under Connections?
• Is the correct Search Box instance selected?
• Does the Query Template contain the token {searchTerms}?
• Was the page republished after the change?

The search page shows no results

An empty result list can have multiple causes:

• The query is too restricted by Path, content type, or file type.
• The content being searched has not yet been added to the search index.
• The logged-in user does not have read permissions for the content.
• An incorrect data source or result source was selected.
• A used managed property is not available or not searchable.
• The search term was not taken from the URL or Search Box.

For troubleshooting, first remove all additional restrictions and test using only {searchTerms}. If the basic search works, the restrictions can then be added back one by one.

Administrators see results, but normal users do not

This behavior is often not a Webpart error. SharePoint Search considers the access rights of the logged-in user. A result is shown only if the user has access to the underlying item.

Therefore, always test with at least two accounts:

• an administrative or highly privileged account,
• a typical user account with the intended standard rights.

If content is found only for the administrative account, check library, folder, item, and site permissions.

The search term does not appear on the target page

First check the browser address. If the parameter is missing there, the error is in the Search Box on the starting page. If the parameter is present but not shown in the search field, the connection between the target Search Box and the page environment is incorrect.

Common causes are:

• different parameter names,
• using a URL fragment on the starting page and a query-string parameter on the target page,
• incorrect target page,
• unpublished changes,
• a connection to another Search Box instance.

Results are displayed twice

The SharePoint Search data source module offers a setting to remove duplicates. This is not enabled by default. Enabling Trim duplicates can reduce hits that the search engine identifies as duplicates.

However, not every duplicate display is a technical duplicate. Often, multiple objects actually exist, for example:

• copies of the same document in multiple libraries,
• a file and a published page with similar content,
• different URLs for various content variants,
• migrations where both the original and the new copy were indexed.

Therefore, check properties such as Path, UniqueID, NormUniqueID, SiteTitle, and ContentTypeId in the debug layout before hiding results in general.

Properties are missing in the layout

A managed property must be returned as a selected property from the data source before it can be used reliably in a layout. If the desired property does not appear in the selection list, its internal name can often be entered manually and confirmed with the Enter key.

For troubleshooting, the debug layout is a good starting point. It shows which properties a hit actually contains. Only after that should an individual result template be adjusted.

Tests and fallback before publishing

A search page should be tested with several known terms. Use a small test matrix with expected results.

Test: Unique document title

Expected behavior: The known document appears near the top.

Test: Term from the document content

Expected behavior: The document is found, provided the content is indexed.

Test: Empty search field

Expected behavior: The defined default behavior is executed.

Test: Invalid term

Expected behavior: An empty result display appears without a page error.

Test: User without access

Expected behavior: Protected content does not appear.

Test: Redirect from the home page

Expected behavior: The URL, search box, and results contain the same term.

Test: Browser back function

Expected behavior: Navigation remains traceable.

Test: Mobile view

Expected behavior: Search box, button, and results remain usable.

Prepare a fallback path

Before making larger changes, keep the existing search page intact. A simple fallback path is to build a new page in parallel and switch existing navigation entries only after tests are complete.

Document at least:

• installed package version,
• name and URL of the search page,
• URL parameters used,
• data source and result source,
• query template,
• selected properties,
• connected web parts,
• additional approved API permissions.

If a change fails, navigation can be redirected back to the previous page without needing to roll back the entire app deployment.

Maintainability and rollout in additional sites

Manual configuration is sufficient for a single search page. For multiple sites, standardize settings and responsibilities.

Document configuration as a technical baseline

Define a reference configuration that describes at least the search box, search results, URL parameters, query template, and required managed properties. This allows deviations between sites to be detected more quickly.

Avoid unnecessarily hard-coding the search scope

Absolute site URLs in query templates are easy to understand but must be adjusted when pages are copied. When rolling out, check whether the search scope should be central, site-specific, or library-specific.

A central search page typically requires a tenant-wide or intranet-wide query. A department-specific page should instead be clearly distinguished by Path, content types, or managed properties.

Perform package updates in a controlled manner

New package versions should first be tested in a test environment or a limited test site. The following are particularly relevant:

• existing Webpart connections,
• custom Handlebars templates,
• Extensibility Libraries,
• used data sources,
• newly requested API permissions,
• display on published pages.

Deleting the package from the App Catalog is not a suitable fallback path for a failed update, as existing Webpart instances can no longer be loaded. A tested version change with a documented previous package version is more appropriate.

Practical example: a central search page in the intranet

In many intranets, the home page should contain only a compact search field, while the actual result display is on a separate page. This appears simple to users but technically requires a clean transition between the Search Box, URL parameters, Search Results, and optional filters.

A robust setup clearly separates the tasks:

Component: Search Box on the home page

Responsibility: Accept the search term and forward it

What to note: Consistent parameter name, for example q

Component: Search Box on the results page

Responsibility: Display the URL value and enable a new search

What to note: Dynamic default value from the page environment

Component: Search Results

Responsibility: Execute the query and display hits

What to note: Query Template with {searchTerms}

Component: Search Filters

Responsibility: Narrow down hits by metadata

What to keep in mind: Use only refinable managed properties.

For future expansion, it is worth looking at the relationship between the search page and PnP Search Filters with Refiners and KQL. The search page should run stably without filters first, before adding Refiners, Verticals, and individual templates.

Quality criteria for result layouts

A result layout must help users quickly evaluate hits. Often, a few well-chosen properties are sufficient: title, path or area, document type, modification date, and a short text excerpt.

• Show only metadata that truly helps with selection.
• Avoid technical property names in visible labels.
• Check long titles and mobile views before publishing.
• Use the debug layout only for configuration, not for production pages.
• Document custom templates so that updates remain traceable later.

This improves the search page's hit rate and orientation within the result set. This is a key factor when users work with search regularly and should not be driven away after a few unsuccessful attempts to folder navigation or personal link collections.

How to keep the search page stable even after the initial configuration

A stable PnP search page starts with the simplest possible setup: Search Box and Search Results on the same page, a SharePoint Search data source, and the unmodified query template {searchTerms}. Only when this data flow works should redirects, URL parameters, filters, Verticals, and individual layouts be added.

For ongoing operations, four points are especially critical: consistent parameter names, documented query templates, tests with realistic user permissions, and a controlled process for package updates. This allows you to quickly distinguish whether the cause of an error lies in the webpart connection, the query, the search index, or access rights.