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!
Top comments (0)