Skip to main content

Search Results

The 'Search Results' Web Part is the fundamental building block of whole global solution. Its purpose is basically to get data from a search index and render them in a specific default or custom layout.

This Web Part can be used alone or connected to other Web Parts to add dynamic interactions (filters, search box or verticals). To use the Web Part on a SharePoint page:

  1. Edit your SharePoint modern page.
  2. Search for the 'PnP Modern Search Core Components - Search Results' Web Part and add it to your page:

Search Results Webpart

Search Results Webpart Default

Configure the search query

Basic mode

The basic mode allows you to quickly get started and configure your query without having a deep knowledge of search concepts.

note

🚧 Basic mode is still under development and will be available soon 🚧

Advanced mode

The advanced mode allows you to fine tune the query settings. However, it requires a minimum knowledge about Microsoft Search concepts as most of the parameters are a wrapper over the Microsoft Search Graph API.

Entity types

Entity types represent the type of data you want to retrieve. The following entity types are available:

Entity typeDescription
List ItemsUsed to retrieve SharePoint list items. Note that files and folders are also returned as list items.
ListSearch for lists. Note that document libraries are also returned as lists.
DriveDocument libraries.
Drive ItemsFiles, folders, pages, and news.
SitesSites in SharePoint.
External ItemsExternal indexed sources. When selecting this option, you must specify a valid connection ID.
Teams messagesMessages fron Microsoft Teams.
BookmarksMicrosoft Search bookmarks defined at organization level.
AcronymsMicrosoft Search acronyms defined at organization level.
MessagesEmail messages from Outlook.
EventsCalendar events from Outlook.

Entity types

warning

Not all entity types can be used together. Refer to the following table to see possible combinations. The Web Part will automatically prevent incompatile combinations as long as you choose options.

Query text

The query text typically represents the free text keywords to search for. Its value can be static or dynamic based on a dynamic value (ex: a search box on the page, a query string parameter, etc.).

Query Text

Static value

Enter a value that will apply every time for the query. You can also use Keyword Query Language as well.

Dynamic value

Use a dynamic value if the search keywords should come from an other source on the page.

note

Theorically, all SharePoint web parts or extensions defined as a source on the page will be listed here. Any string value from a source can be used as query text.

You can connect the PnP Modern Search Core Components - Search Box as query text source for the search results Web Part. To do so:

  1. Add the 'PnP Modern Search Core Components - Search Box' on the same page.
  2. Open the 'PnP Modern Search Core Components - Search Results' property pane settings.
  3. In Query TextDynamic ValueConnect to source, choose PnP Modern Search Core Components - Search Box.
  4. In PnP Modern Search Core Components - Search Box's properties choose your Search Box WebPart.

Connect search box

Find Web Part instance ID

To find the Web Part instance ID ➝ here

➔ Use a default value

When connecting to dynamic source, you can also set a default value. This option is useful when no keywords are specified by default (ex: an empty search box)

Default value

Query template

The search query template to use. It allows you to use dynamic tokens according to the context or specify conditions that should always apply to the query. You can also use Keyword Query Language as well here.

Default value

Working with tokens

To see the list of allowed tokens please refer to this page.

Advanced settings

Selected fields

The selected fields represent the field values that should be included in the search response. Then, these values can be used in results, eiher to be displayed (ex: display the result title or created date for each result item) or for computing purpose (ex: build an URL with an ID).

  • To add a new field, enter the name in the textbox box ➝ press "Enter".
  • To remove a field, open the list ➝ de-select the field from the list.

Default value

info

With Microsoft Search, fields depends on the entity types you query. For instance, with listItem, sites and driveItem, you can retrieve SharePoint managed properties but also some properties specific to the driveItem underlying Microsoft Graph resource type (ex: lastModifiedBy). Refer to the Microsoft Graph API reference to see all available properties per entity types (complex properties like relationships can't be retrieved this way however).

Fields you can retrieve per entity types:

Entity typeFrom search schemaFrom Graph resource type
Drive Items✔️ (SharePoint)✔️ (Link)
List Items✔️(SharePoint)
Sites✔️(SharePoint)✔️ (Link)
Lists✔️ (SharePoint)✔️ (Link)
Drives✔️(SharePoint)✔️(Link)
Teams messages✔️ (Link)
Bookmarks✔️ (Link)
Acronyms✔️ (Link)
Messages✔️(Link)
Events✔️(Link)
External Items✔️(Specific to source)
warning

Specify only fields you need. More you add fields in the response, more the results will be slow to appear.

Configure filters and sorting

Filters

See the 'Search filters' documentation for the configuration process.

Sorting

The sort options are managed in the Search Results web part but requires a connected search filters filters to be displayed

SettingDescription
Sort fieldThe sort field name to use. The field needs to be sortable/refinable in the search schema.

warning
There is not more 'Sortable' attribute with Microsoft Search. A property is sortable as long it is Refinable in the search schema.
Sort directionThe sort direction to use by default (ascending/descending).
Is default sortIndicates if the sort is applied by defaut in the query. If the sort field/direction is not
Is user sortIndicates if the sort can be set by users manually.

info
➝ Sort fields are displayed in the connected search filters (right position, cannot be changed).

➝ When default sort and user sort options are both enabled, items are sorted by default as long user do not modify the sort field/direction manually.

➝ The Relevance sort field is the same as if no sort was selected.

Sort field
Display nameIf user sort is enabled, the name of the field as seen by users in the search filters web part.

Add sort property

Working with result types

Result types are JSON adaptive cards managed centrally from the Microsoft Search admin portal and are defined per source. It allows to streamline the UI experience across all search locations. Enable this option only if you want to rely on the managed experience instead of the web part builtin templates.

Default value

Don't forget to define fields!

Most of the time, result types expect specific fields to be included in the search response to work properly. If you are not sure what fields to use, contact an admin.

Use beta endpoint

The beta option switches the underlying Microsoft Search Graph API endpoint from v1.0 to beta.

Use beta endpoint

Not for production

The beta endpoint is not suitable for production usage and it is not supported by our team nor by Microsoft. It should be used only for test/development purposes.

Query modifications

If enabled, the user gets the search results for the corrected query if there were no results for the original query with typos. It means the query will be automatically modified.

Enable modifications

warning

🚧 As of today, there is no way for user to see if the query has been moddified or not in the UI when results are displayed. 🚧

Paging settings

The paging options are available for all data sources.

Enable modifications

SettingDescription
Show pagingHide or display the paging control.
Page sizeThe size of the page to be retrieved. The maximum value is 500.
Number of pages to showDetermines the number of pages to display in range. Minimum 1 to 20. If your request returns more than 2000 pages, you'll see a "Too many pages" message. This is to avoid any empty pages due a Microsoft Search API limitation.
warning

We recommend to limit the number of items per page betwen 10 and 20 to manage performances.

Pre-built templates

The search results provides pre-built templates you can use to display results.

Default (List)

By default, items are rendered in list format.

Example: news item

List Item news

Example: PDF file

List Item PDF

info

Icons and properties are automatically displayed according to entity type.

Tiles

The tiles template displays items in cards. Example with Anvil SharePoint site:

Cards

The following options are available:

⚙️ Control the number of cards displayed according to Web Part width

To make sure the dsiplay is responsive, you can control the number of cards dispkayed according to the Web Part container width, for instance if the page is displayed from a mobile.

  1. ➝ Select the width breakpoint:

WebPart width breakpoints

  1. ➝ Select the number of cards to display for this width:

Number of cards

warning

Breakpoints are relative to the Web Part container width, not the page width.

Generic options

Show count

The show count option display the total number of results returned by the query.

Show count option

Show count example

Control Web Part visibility with search verticals

You can connect the search results Web Part to a search verticals on the same page:

  1. Add a 'PnP Modern Search Core Components - Search Verticals' Web Part on the page and configure some tabs.

Results display

  1. Enable the Use verticals option ➝ Choose the verticals Web Part to connect to:

Use verticals

Find Web Part instance ID

To find the Web Part instance ID ➝ here

  1. Choose tabs where the search results Web Part should be displayed when selected.

Select verticals

info

The verticals control the entire visiblity of the Web Part. When the vertical is not selected, nothing is rendered and no query is made.

Customize templates

Working with templates

To know how to author templates, refer to the general guidelines.

The search results web part provides the following templates to be overriden:

items

This template controls the rendering of each results item:

Properties

The following properties can be used in the template:

PropertyDescription
itemsArray of items returned by search results. For convenience, all properties are flatten automatically (ex: instead of items.resource.fields.myProperty, you can use directly items.myProperty).

warning
Field properties are case sensitive (ex: item.Path is different from item.path)
totalCountThe count of items returned.
filtersThe available filters provided by the data source according to the filters configuration provided from the data context (if applicable).
resultTemplatesResult templates available for items provided by the data source.
rawResponseThe raw response payload received from the Microsoft Search Graph API.
rawRequestThe raw request payload sent to Microsoft Search Graph API.
<template data-type="items">
<div data-for='item in items'>
<div>Title: {{ item.title }}</div>
<div>Path: {{ item.path }}</div>
</div>
</template>

Items template

shimmers

This template controls the rendering of shimmers before results are fetched and displayed.

Properties

The following properties can be used in the template:

PropertyDescription
itemsArray of empty items sized according the configured number of items per page.
<template data-type="shimmers">
<div data-for="i in items">

<div class="animate-shimmer pb-8">
<div class="flex space-x-2 mb-2">
<div class="w-6 h-6 rounded bg-slate-200"></div>
<div class="w-96 h-6 rounded bg-slate-200"></div>
</div>
<div class="flex space-x-2 mb-2">
<div class="w-16 h-3 rounded bg-slate-200"></div>
<div class="w-16 h-3 rounded bg-slate-200"></div>
<div class="w-16 h-3 rounded bg-slate-200"></div>
</div>
<div class="flex flex-col mb-4 space-y-2">
<div class="w-full h-3 rounded bg-slate-200"></div>
<div class="w-96 h-3 rounded bg-slate-200"></div>
</div>
</div>

</div>
</template>

Shimmers template

Template slots

The search results web part provides some predefined slots for templates:

Template slots

Slots are placeholders defined on templates that can be mapped either to a specific field retrieved from results (ex: a value you specified in the Fields option in the search results web part settings) or a static value (ex: an arbitrary URL). They are especially useful if you only need small updates, like changing the value of a specific field in the result visual without udpating the entire template.

warning

Slots from Default layout can't be removed (only modified, except the title). To define your own slots, you need to switch to the Custom layout.

  1. In the search results web part, configure the query settings to get at least one result (this step is important to lookup all available fields from the response).
  2. Enable Use dynamic field value option.
  3. In Slot value ➝ select a field from the list.

Dynamic slot value

warning

If there are no results currently displayed, the fields list will be empty

Use slots in custom templates

In custom made templates slots can be referenced like this:

<div>Title: {{ slot("Name of my slot",item) }}</div>