Choose your list in SPFx using the PnP ListPicker control

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

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

The ListPicker control is used to display a dropdown where the user can see and select the available SharePoint lists.

Starting with the UI aspect of the control: it displays a simple dropdown, as you can see in the following screenshot there are multiple instances of the control but apparently all look like the same, the differences are in the resulting behavior of the single instances.

Starting as usual with the basic control usage, this instance uses the minimal needed configuration and takes advantage of the default values.

As said, the control will display a dropdown that enables the user to select a list, in my test environment the resulting when clicking on the control, is the following:

Keep in mind the first empty option, I will explain it later in the code section. The options are all the lists available in the current SharePoint site. By default all the visible and hidden lists are available and also by default the sorting is based on the lists titles.

Speaking of visible and hidden lists, it is possible to declare if the user is allowed to see or not the hidden ones, for example in the second control instance I only want the visible ones to be selectable, in fact the resulting options are:

Proceeding with the control instances we can see a different sorting order. By default the sorting will be applied comparing the lists titles but another one is available and is the ID sorting, in the sample the resulting will be:

Which, as you can see, is pretty different than the display order of the basic instance.

Another useful setting is the possibility to allow multiple selection of the options, this will add a checkbox beside each option to allow the user to select many options as wanted:

You can also specify a couple of custom strings for the control, by default no string will be shown but if needed you can specify either a label or a placeholder to be shown as in the “Custom strings” instance:

Another useful ability of the control is that you can filter the available lists by the supported content type in order to show only the lists that support a specific content type:

It is also possible to define a variable to handle the refresh of the options available in the control, in the sample I’ve added an IconButton to enable the user to refresh the content of the dropdown:

I will cover in detail how this works in the code section.

Finally there’s the ability to specify a custom OData query filter. In the sample I’ve filtered out all the lists that were created before a specific date, in fact the available options are greatly reduced:

Enough of the talking now, let’s switch to 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 ListPicker control.

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

import { ListPicker } from "@pnp/spfx-controls-react/lib/ListPicker";

The control works using the context of the web part so you will have to pass the WebPartContext object using the component properties when instancing the web part component, in the sample I used the following code inside the web part class in the render method:

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

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

Doing so will allow you to use the web part context in the web part component and use it with the various control instances.

Just for reference the context property is defined as follows:

import { WebPartContext } from "@microsoft/sp-webpart-base";

export interface IListPickerSampleProps {
  context: WebPartContext;
}

Now that all the required code is in place we can proceed and have a look at the actual ListPicker code.

Basic instance

The basic instance contains the minimum code requirements, actually in the sample it contains also a non required property but I will explain it in a second. The minimal code is:

<ListPicker
  context={this.props.context}
  onSelectionChanged={this.onListSelected} />

The only truly required property for the control is the context one, however in the sample solution I’ve also defined, for each instance of the control, the onSelectionChanged property to allow you to check in the browser console what has been selected. The code used for the onSelectionChanged method is the following:

private onListSelected(lists: string | string[]): void {
  console.log("Lists:", lists);
}

Remember when before I was talking about the first empty option? Let’s talk a little bit about it. When selecting any of the available list options the resulting will be a single (or an array of strings) that contains the id of the selected list, in case the user selects the first empty item the returned string will be NO_LIST_SELECTED so please take this into consideration when using the control.

Hide hidden lists

The control, by default, shows all the available lists whether those are visible to the user or hidden. Using the includeHidden control property you can specify if the hidden lists will be shown or not:

<ListPicker
  context={this.props.context}
  includeHidden={false}
  onSelectionChanged={this.onListSelected} />

Order by

You can define how the control will sort the available options. By default the sorting will be by list title but you can also specify the sorting to be by ID.

At the time of writing the orderBy property accepts an enum value that contains the following values:

export declare enum LibsOrderBy {
  Id = 1,
  Title = 2
}

In this case the control instance is defined as:

<ListPicker
  context={this.props.context}
  orderBy={LibsOrderBy.Id}
  onSelectionChanged={this.onListSelected} />

Multiple selection

In case you need to allow the user to perform multiple selections you can set the multiSelect property to true, this will add a checkbox beside each of the options displayed and also will return an array of strings to the onSelectionChanged property:

<ListPicker
  context={this.props.context}
  multiSelect={true}
  onSelectionChanged={this.onListSelected} />

Just a quick note: the onSelectionChanged will be called everytime the user checks or unchecks an option.

Custom strings

As said before it’s possible to define a couple of custom strings and those are represented by the label and the placeHolder properties. The label one will add a label above the dropdown control, the placeHolder instead will be shown inside the dropdown:

The code to achieve this is the following:

<ListPicker
  context={this.props.context}
  label={strings.CustomStrings.Label}
  placeHolder={strings.CustomStrings.PlaceHolder}
  onSelectionChanged={this.onListSelected} />

Filter by content type

It’s possible to filter the available lists by their content type using the contentTypeId property, this will show all the lists that contains the specified content type, all the other lists will not be shown. In the sample I’ve used the Document content type (0x0101):

<ListPicker
  context={this.props.context}
  contentTypeId={'0x0101'}
  onSelectionChanged={this.onListSelected} />

Refreshing the options

It’s possible that, while the user is using the control, a new list is created. In this case the new list won’t be shown in the control until the page is refreshed. To avoid this situation you can bind a value to the refreshToggle property, doing so each time the value change the control will refresh the available options. In the sample I’ve used a boolean value from the state that will be updated when pressing the IconButton that I’ve added after the ListPicker control:

<ListPicker
  context={this.props.context}
  refreshToggle={this.state.refreshLists}
  onSelectionChanged={this.onListSelected} />
<IconButton
  iconProps={{ iconName: 'Refresh' }}
  onClick={() => {
    this.setState({
      refreshLists: !this.state.refreshLists
    });
  }}
/>

Custom filtering

Aside of the filtering for the visible/hidden lists or by the content type, there is also the possibility to use an OData filter to perform a more granular filtering. In the sample I’ve set the filter property to display all the lists that are created after the specified date:

<ListPicker
  context={this.props.context}
  filter={'Created gt datetime\'2024-07-01T00:00:00Z\''}
  onSelectionChanged={this.onListSelected} />

Conclusions

The ListPicker control is quite a useful one when it comes to enable the user to select a SharePoint list (or lists), it allows you to speed up your coding process since all you have to do is handle the selection and it will handle all the list retrieval and filtering!

In this article I didn’t cover all of the available properties, if you want to check out what are the remaining ones or if you want to have a look at the official documentation you can find it here.

Hope this helps!