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

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

The ListItemPicker control is used to display a dropdown where the user can see and select the available list items from a specific SharePoint list.

This sample uses the PnP ListPicker control to enable the selection of a list in the current SharePoint site, if you want to know more about it you can check my other blog post here.

Starting with the sample solution screenshots, initially the user has to select the SharePoint list from where the ListItemPicker will retrieve the available list items:

Once selected the source list all the ListItemPicker instances will be shown:

Now that we have a general idea of the UI structure of the solution let’s have a closer look at each of the instances.

The minimal configuration instance is used to display what’s the default behavior of the ListItemPicker. When the user clicks on the control it will not display anything even if the selected list contains items:

To select the existing items it’s required to start typing some text inside the control:

Keep in mind that, by default, the control will check if the item field starts with the inserted text.

Once the item is selected the control will look like the following:

The default selected items instance is used to display the ability to define the already selected items:

In the next instance, which is similar to the previous one, the main point is to highlight the behavior of the control when is disabled:

The suggestions enabled instance shows that it’s possible to, as the name evoke, enable the suggestions when clicking on the control. This is handy in order to not require the user to type any text to display the selectable items:

In some situation is required to let the user select multiple items and the next instance displays this possibility:

A useful customization is the possibility to define some custom strings, in the following screenshot you can see the label and a place holder defined:

Other than the previous strings there are also other strings inside the panel that opens when the user clicks inside the control:

As said before, the default search behavior is to compare the start of the strings with the specified text, there is also the ability to change this into a substring in order to search in the whole string instead of just the beginning:

Speaking of filtering there is also the capability to use an OData filter to show only certain items, in the following I defined a query that shows only the item with the “Test 3” title:

Last but not least there’s also a property to define the sorting using an OData string, in this case I started typing “T” and the control shows all the items that starts with that string and order those in descending order:

Now it’s time to cover 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 to use the ListItemPicker control.

To use the control you first need to import it and that can be done as following:

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

After importing the control the target list id is needed, to overcome this I used a ListPicker to not hardcode the value in the code. If you want to know more about the ListPicker control you can check this article.

NB : in this solution I used a list that has the Id and Title fields, if you need to test the solution with other fields you will need to change the control properties to reflect your needs.

Now that we have the requirements let’s cover the various control configurations.

Minimal configuration

As said before the minimal configuration is the instance that requires the minimum amount of configuration and rely on the default values for the non specified properties. In the sample the code is:

<ListItemPicker
  context={this.props.context}
  listId={this.state.selectedList}
  columnInternalName='Title'
  itemLimit={1}
  onSelectedItem={this.onListItemSelected} />

The specified properties of the above code are also the required ones, without those the control cannot be instantiated. Those properties are:

• context: this property needs the web part context, you can retrieve that in the main web part class.
• listId: the GUID of the list from which the control will retrieve the list items.
• columnInternalName: the internal name of the column that contains the text value of the list items, in this case it will use the Title column to display the list items and this column will also be used for the search capability.
• itemLimit: this numeric value represent the number of list items that can be selected.
• onSelectedItem: a function that handles the selection for the list items.

In the sample solution I defined a method to be used in every control instance, this method is used only to display in the browser’s console the selected list item values. Here, for reference, the code of the method:

private onListItemSelected(data: { key: string; name: string }[]): void {
  for (const item of data) {
    console.log(`Item value: ${item.key}`);
    console.log(`Item text: ${item.name}`);
  }
}

The properties covered until here are the required ones and thus all the control instances will need to have those defined. To avoid repetitions, in the rest of this article, I will focus only on the specific properties.

Default selected items

It is possible, using the defaultSelectedItems property, to define one or multiple items already selected when the control first renders. It is also possible to specify list items that don’t exist on the specified list.

In the instance code I defined a custom item:

<ListItemPicker
  context={this.props.context}
  listId={this.state.selectedList}
  columnInternalName='Title'
  itemLimit={1}
  onSelectedItem={this.onListItemSelected}
  defaultSelectedItems={[{"key": "custom","name":"Custom list item"}]} />

The defaultSelectedItems property value must be an array of objects with the key and name properties defined.

Disable the control

There’s the ability to disable the control, in this manner it will still display the selected item/s but will not allow the user to change it’s content. Disabling the control can be achieved simply by setting the disabled property to true:

<ListItemPicker
  context={this.props.context}
  listId={this.state.selectedList}
  columnInternalName='Title'
  itemLimit={1}
  onSelectedItem={this.onListItemSelected}
  disabled={true}
  defaultSelectedItems={[{"key": "custom","name":"Custom list item"}]} />

Enabling suggestions

By default the control won’t show any of the existing list items unless the user starts typing, it’s useful to know that is possible to change this behavior. Using the enableDefaultSuggestions property it’s possible to, when the user clicks on the control, have the list items shown:

<ListItemPicker
  context={this.props.context}
  listId={this.state.selectedList}
  columnInternalName='Title'
  itemLimit={1}
  onSelectedItem={this.onListItemSelected} 
  enableDefaultSuggestions={true} />

Key column

Using the keyColumnInternalName property it’s possible to define which column of the list items should be used as the key value of the object that the onSelectedItem receive. By default the key value uses the Id column unless a different column is specified. In the sample I used the property to explicitly specify the Id column:

<ListItemPicker
  context={this.props.context} 
  listId={this.state.selectedList}
  columnInternalName='Title'
  keyColumnInternalName='Id'
  itemLimit={1}
  onSelectedItem={this.onListItemSelected}/>

Multiple selection

The ListItemPicker control offers the capability to allow the user to select a single or multiple elements. To enable the different selection modes you have to use the itemLimit property which accepts a numeric value and the number specified represents the number of selectable list items. In the following code the limit is 3 list items:

<ListItemPicker
  context={this.props.context} 
  listId={this.state.selectedList}
  columnInternalName='Title'
  itemLimit={3}
  onSelectedItem={this.onListItemSelected} />

String customization

Often there’s the need to define custom string instead of the default ones, the control allows the definition of four different strings:

• label: the string to be displayed before of the actual control.
• placeholder: the string to be displayed inside of the control.
• suggestionsHeaderText: this is the string displayed in the panel that opens when the user clicks on the control.
• noResultsFoundText: the text that will displayed in the panel when no result is found.

Following you can see how to use those properties:

<ListItemPicker
  context={this.props.context} 
  listId={this.state.selectedList}
  columnInternalName='Title'
  itemLimit={1}
  onSelectedItem={this.onListItemSelected}
  suggestionsHeaderText={strings.CustomStrings.Header}
  noResultsFoundText={strings.CustomStrings.NoResults}
  placeholder={strings.CustomStrings.PlaceHolder}
  label={strings.CustomStrings.Label} />

Substring search

A useful feature of the control is the ability to change the search behavior, from the default that search if the list item text starts with the entered string, to the substring search that filters the list items that contains the entered string. To enable this feature is enough to set the substringSearch to true:

<ListItemPicker
  context={this.props.context}
  listId={this.state.selectedList}
  columnInternalName='Title'
  itemLimit={1}
  onSelectedItem={this.onListItemSelected}
  substringSearch={true} />

Filtering

Aside of the capabilities to filter the list items by the specified text it’s possible to define an OData filter that is applied by default to customize the retrieved list items. To specify the OData filter you can use the filter control property:

<ListItemPicker
  context={this.props.context}
  listId={this.state.selectedList}
  columnInternalName='Title'
  itemLimit={1}
  onSelectedItem={this.onListItemSelected}
  filter="Title eq 'Test 3'" />

In this code snippet only the list items that have a title equals to “Test 3” will be displayed.

Sorting

The last control property that I want to cover is the orderBy property. This property enables to order the retrieved list items by the OData sorting specified.

<ListItemPicker
  context={this.props.context}
  listId={this.state.selectedList}
  columnInternalName='Title'
  itemLimit={1}
  onSelectedItem={this.onListItemSelected}
  orderBy="Title desc" />

In the code snippet the retrieved list items will be sorted by the Title column in descending order.

Conclusions

The ListItemPicker is quite a nice addition to leverage the selection of list items. It can be handy in those situations where the user is required to select one or multiple list items for your application.

All the properties of the control offer a very customizable behavior from the filtering, to sorting, and to string customization.

If you want to know more about this useful control you can have a look at the official documentation here.

Hope this helps!