Discover the SitePicker control from the PnP React controls

Proceeding with the appointments with the PnP React controls today I want to talk about the SitePicker control.

If you’re interested you can find the code of this sample here.

The SitePicker control is used to allow the selection of a single or multiple sites.

Starting from the beginning, I’ve prepared a sample solution to show how the resulting control instances look like.

At first sight all the instances look the same but the behaviors are pretty different. Starting with the Basic usage instance, when the user clicks on the control a list of available web will be shown.

In my demo environment, using the default behavior, when the user clicks on the control the result is the following:

As you can see there is a text box at the top which enables to specify a search query to filter the results:

Also, by default, the multiple selection is the default behavior so you’ll see the checkboxes aside of the name and relative URL of the options. In case you’re using the single selection mode you won’t have the checkboxes.

When a site or multiple sites are selected you’ll see the result in the control:

I will cover the different instances in the code section as the UI would not be as useful as seeing the code.

Show me the code

To use the PnP React controls first you need to install the package:

npm install @pnp/spfx-controls-react --save --save-exact

After the installation of the package you can proceed with the following instructions for the SitePicker control.

The control works using the context of the web part so you will have to pass the WebPartContextobject using the component properties when instancing the web part component, in the sample I used the following code:

public render(): void { 
 const element: React.ReactElement<IPnPSitePickerProps> = React.createElement(
  PnPSitePicker,
  {
   context: this.context,
  }
 );

 ReactDom.render(element, this.domElement);
}

Once that you have the web part context available you will have to import the SitePicker control in the web part component:

import { SitePicker } from '@pnp/spfx-controls-react/lib/SitePicker';

Next let’s talk about the various possible configurations of the control.

The Basic usage instance is the minimal allowed configuration and is defined as following:

<SitePicker
  context={this.props.context as any}
  onChange={(site) => {
    console.log(site);
  }}
/>

The properties set in this instance will be mandatory for the control to work, all the instances have those properties defined, the following are the mandatory properties:

• context : which is the context of the web part and is of type WebPartContext.
• onChange : this handler will be called when changing the selection of the control and receive an array of ISite containing the selected items. The ISite interface contains four useful properties:
  • id
  • title
  • url
  • webId

The next instance of the control is the deferred search time one and this shows how to use the deferredSearchTime property which accepts an integer representing the milliseconds to wait before executing the search:

<SitePicker
 context={this.props.context as any}
 deferredSearchTime={2000}
 onChange={(site) => {
  console.log(site);
 }}
/>

Another interesting property of the control is displayed in the disable search instance which, as the name suggests, shows how to disable the search in the dropdown panel and to do so you have to simply set the allowSearch property to false:

<SitePicker
 context={this.props.context as any}
 allowSearch={false}
 onChange={(site) => {
  console.log(site);
 }}
/>

The next instance, the entities available one, will show how it’s possible, using the mode property, to select which kind of entities are shown in the selectable items. The available values for the mode property are the following:

• site
• web
• hub
• associatedsites

In the sample this instance is set to use only the site entities:

<SitePicker 
 context={this.props.context as any}
 mode='site'
 onChange={(site) => {
  console.log(site);
 }}
/>

Proceeding with the next instance, the single selection one, you will see how to disable the multiple option selection (which, as said before, is the default behavior of the SitePicker control) using the multiSelect property:

<SitePicker
 context={this.props.context as any}
 multiSelect={false}
 onChange={(site) => {
  console.log(site);
 }}
/>

Another useful property is the orderBy one, displayed in the order by url instance, this property allows you to order the options by two possible values:

• title
• url

The code of this instance is the following:

<SitePicker
 context={this.props.context as any}
 orderBy='url'
 onChange={(site) => {
  console.log(site);
 }}
/>

Finally there’s the custom labels instance which shows what are, using the control properties, the customizable strings. The available properties are:

• label: adds a label on the top of the control displaying the specified text.
• placeholder: shows the specified text inside the control when there is no option selected yet.

The code of this instance is:

<SitePicker
 context={this.props.context as any}
 label={strings.Label}
 placeholder={strings.Placeholder}
 onChange={(site) => {
  console.log(site);
 }}
/>

To sum up

The SitePicker control is a very useful and easy to use one that allows the selection of a single or multiple sites, it can be used for example to allow the user to select a site to be targeted for some specific operation. There are many ways to use it but what I like the most is that it’s a ready to use control so you don’t have to write any code to retrieve sites or webs and bind them to a control, it already does all of this!

Hope this helps!