

PropertyFieldListPicker control

This control generates a list picker field that can be used in the property pane of your SharePoint Framework web parts.

The control can be configured as a single or multi-selection list picker:

Single list picker

Multi list picker

How to use this control in your solutions

1. Check that you installed the @pnp/spfx-property-controls dependency. Check out The getting started page for more information about installing the dependency.
2. Import the following modules to your component:

import { PropertyFieldListPicker, PropertyFieldListPickerOrderBy } from '@pnp/spfx-property-controls/lib/PropertyFieldListPicker';

1. Create a new property for your web part, for example:

export interface IPropertyControlsTestWebPartProps {
  lists: string | string[]; // Stores the list ID(s)
}

1. Add the custom property control to the groupFields of the web part property pane configuration:

PropertyFieldListPicker('lists', {
  label: 'Select a list',
  selectedList: this.properties.lists,
  includeHidden: false,
  orderBy: PropertyFieldListPickerOrderBy.Title,
  disabled: false,
  onPropertyChange: this.onPropertyPaneFieldChanged.bind(this),
  properties: this.properties,
  context: this.context,
  onGetErrorMessage: null,
  deferredValidationTime: 0,
  key: 'listPickerFieldId'
})

Implementation

The PropertyFieldListPicker control can be configured with the following properties:

Property	Type	Required	Description
label	string	yes	Property field label displayed on top.
disabled	boolean	no	Specify if the control needs to be disabled.
context	BaseComponentContext	yes	Context of the current web part.
selectedList	string | string[] | IPropertyFieldList | IPropertyFieldList[]	no	Initial selected list set of the control.
baseTemplate	number	no	BaseTemplate ID of the lists or libraries you want to return.
includeHidden	boolean	no	Specify if you want to include hidden lists in the list picker. By default this is set to true.
orderBy	PropertyFieldListPickerOrderBy	no	Specify the property on which you want to order the retrieve set of lists.
multiSelect	boolean	no	Specify if you want to have a single or multi-list picker. By default this is set to false (single list picker).
showSelectAll	boolean	no	Specify if you want the Select All checkbox. By default this is set to false (mult-list picker only).
selectAllInList	boolean	no	Specify where to show the Select All checkbox. When false (default), checkbox is shown before the label, when true it is shown with the lists (mult-list picker only).
selectAllInListLabel	string	no	The label to use for the in list select all checkbox (mult-list picker only).
webAbsoluteUrl	string	no	Absolute Web Url of target site (user requires permissions)
onPropertyChange	function	yes	Defines a onPropertyChange function to raise when the date gets changed.
properties	any	yes	Parent web part properties, this object is use to update the property value.
key	string	yes	An unique key that indicates the identity of this control.
onGetErrorMessage	function	no	The method is used to get the validation error message and determine whether the input value is valid or not. See this documentation to learn how to use it.
deferredValidationTime	number	no	Control will start to validate after users stop typing for deferredValidationTime milliseconds. Default value is 200.
listsToExclude	string[]	no	Defines list titles which should be excluded from the list picker control (list title or ID).
filter	string	no	Filter list from OData query (takes precedence over Hidden and BaseTemplate Filters).
onListsRetrieved	(lists: ISPList[]) => PromiseLike | ISPList[]	no	Callback that is called before the dropdown is populated.
includeListTitleAndUrl	boolean	no	Specifies if the picker returns list id, title and url as an object instead on id.
contentTypeId	string	no	Specifies a content type ID , or a portion of one. If specified, all the lists presented in the control will have at least one content type beginning with the specified content type id.

Interface IPropertyFieldList

Property	Type	Required	Description
id	string	yes	The ID of the list
title	string	no	List's title
url	string	no	List's server relative url

Enum PropertyFieldListPickerOrderBy

Name	Description
Id	Sort by list / library ID
Title	Sort by list / library title