DEV Community

Guido Zambarda
Guido Zambarda

Posted on • Originally published at iamguidozam.blog on

Discover the ComboBoxListItemPicker control from the PnP reusable React controls

#spfx #pnp #react

Introduction

Continuing our exploration of the PnP React controls, today I want to talk about the ComboBoxListItemPicker control, a powerful component that combines the functionality of a combobox with SharePoint list item selection capabilities.

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

The ComboBoxListItemPicker control allows users to select one or more items from a SharePoint list using a combobox interface. The control provides a list of options, suggestions based on user input and supports various configuration options for filtering, ordering, and customization.

This control is particularly useful when you need to:

  • Allow users to select items from large SharePoint lists
  • Filter list items based on specific criteria
  • Support both single and multiple item selection
  • Integrate seamlessly with SharePoint Online environments

Visual appearance

The ComboBoxListItemPicker control offers a wide range of configuration options. Let me showcase some of the various features and functionalities available.

Basic Single Selection

Starting with the minimal configuration, this is how the control appears with basic single-item selection:

The control displays a clean combobox interface to select the item(s) needed.

Once selected an item(s) it will be displayed in the control as follows:

Multiple Selection Mode

When configured for multiple selections, the control allows users to select several items from the list:

Selected items are displayed inside the control, and users can easily remove them by deselecting those from the dropdown options.

Filtered Results

The control supports OData filtering to show only specific items that match certain criteria:

In this example, the filter is applied to show only items with the word “different” in the title, demonstrating how you can programmatically restrict the available options based on your requirements.

Default selection

It’s possible to set programmatically the selected items so the user will find those already selected in the UI:

Ordered and Limited Results

You can configure the control to show a limited number of items and order them according to specific criteria:

This example shows only the top 3 items ordered alphabetically in a descending order, which is useful for large lists where you want to show only the most relevant options.

Disabled State

The control also supports a disabled state for scenarios where interaction should not be allowed:

Show me the code

Prerequisites

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


npm install @pnp/spfx-controls-react --save --save-exact
Enter fullscreen mode Exit fullscreen mode

After the installation of the package, you can proceed with the following instructions to use the ComboBoxListItemPicker component.

To use the control, you first need to import it:


import { ComboBoxListItemPicker } from '@pnp/spfx-controls-react/lib/ListItemPicker';
Enter fullscreen mode Exit fullscreen mode

Now that you understand how to install and import the component, let’s explore the different usage scenarios.

Basic Single Selection

The simplest implementation allows single item selection from a SharePoint list:


<ComboBoxListItemPicker
  listId={listId}
  columnInternalName='Title'
  keyColumnInternalName='ID'
  onSelectedItem={this._onSelectionChanged}
  webUrl={context.pageContext.web.absoluteUrl}
  spHttpClient={context.spHttpClient as any}
  label={strings.SelectAnItem}
  suggestionsHeaderText={strings.AvailableItems}
  noResultsFoundText={strings.NoItemsFound}
/>
Enter fullscreen mode Exit fullscreen mode

The required fields in order to instantiate the control are the following:

  • webUrl: current web URL, retrievable from the web part context.
  • listId: the ID of the list from which the control will retrieve the items to display. In this sample, the selection of the listId value is done using the property pane with the PropertyFieldListPicker (more here).
  • columnInternalName: the name of the column used to display the options in the dropdown menu.
  • spHttpClient: the SharePoint HTTP client, retrievable from the web part context.
  • onSelectedItem: a function to define what happens when an item is selected.

In the sample, the onSelectedItem property, is set to a function that handles the selection change:


private _onSelectionChanged = (items: any[]): void => {
  console.log('Selected items:', items);
  this.setState({ selectedItems: items });
};
Enter fullscreen mode Exit fullscreen mode

Multiple Selection Mode

It’s possible to enable multiple selection by setting the multiSelect property to true:


multiSelect={true}
Enter fullscreen mode Exit fullscreen mode

The full code of this instance is something like the following:


<ComboBoxListItemPicker
  listId={listId}
  columnInternalName='Title'
  keyColumnInternalName='ID'
  onSelectedItem={this._onMultipleSelectionChanged}
  webUrl={context.pageContext.web.absoluteUrl}
  spHttpClient={context.spHttpClient as any}
  multiSelect={true}
  label={strings.SelectMultipleItems}
  suggestionsHeaderText={strings.ChooseItemsMultiple}
  noResultsFoundText={strings.NoMatchingItemsFound}
/>
Enter fullscreen mode Exit fullscreen mode

With OData Filter

It’s possible to apply filters to show only specific items using OData syntax. In the sample you can see that it’s using the following filter:


substringof('different', Title)
Enter fullscreen mode Exit fullscreen mode

In short, it will load all the items that have the string “different” in the title of the item.

The complete code for this control instance is the following:


<ComboBoxListItemPicker
  listId={listId}
  columnInternalName='Title'
  keyColumnInternalName='ID'
  filter="substringof('different', Title)"
  onSelectedItem={this._onFilteredSelectionChanged}
  webUrl={context.pageContext.web.absoluteUrl}
  spHttpClient={context.spHttpClient as any}
  label={strings.SelectItemsContaining}
  suggestionsHeaderText={strings.AvailableItemsFiltered}
  noResultsFoundText={strings.NoItemsFoundFilter}
/>
Enter fullscreen mode Exit fullscreen mode

With Default Selection

You can provide pre-selected items using the defaultSelectedItems property, for example:


defaultSelectedItems={[{ ID: 1 }, { ID: 3 }]}
Enter fullscreen mode Exit fullscreen mode

With the above code the component will be instantiated with two items selected, one with ID 1 and one with ID 3 which, in my sample, are the real IDs of the list item I have in my target SharePoint list.


<ComboBoxListItemPicker
  listId={listId}
  columnInternalName='Title'
  keyColumnInternalName='ID'
  defaultSelectedItems={[{ ID: 1 }, { ID: 3 }]}
  onSelectedItem={this._onDefaultSelectionChanged}
  webUrl={context.pageContext.web.absoluteUrl}
  spHttpClient={context.spHttpClient as any}
  multiSelect={true}
  label={strings.PreSelectedItemsExample}
  suggestionsHeaderText={strings.ItemsPreSelected}
  noResultsFoundText={strings.NoItemsAvailable}
/>
Enter fullscreen mode Exit fullscreen mode

The structure of the array to be set in the defaultSelectedItems property can contain objects with only a property identifying the selected items.

With Item Limit and Ordering

The control offers the ability to limit the number of displayed items and control their order. Here is the full control declaration:


<ComboBoxListItemPicker
  listId={listId}
  columnInternalName='Title'
  keyColumnInternalName='ID'
  itemLimit={3}
  orderBy='Title desc'
  onSelectedItem={this._onLimitedSelectionChanged}
  webUrl={context.pageContext.web.absoluteUrl}
  spHttpClient={context.spHttpClient as any}
  label={strings.LimitedSelection}
  suggestionsHeaderText={strings.TopItemsAZ}
  noResultsFoundText={strings.NoMatchingItemsTop5}
/>
Enter fullscreen mode Exit fullscreen mode

Among the properties of the control there is the property itemLimit, this property will specify how many items the control will display. In the above code the item limit is set to 3.

To sort the items you can use the orderBy property. This property will accept an OData sorting string, in the sample it’s using:


Title desc
Enter fullscreen mode Exit fullscreen mode

And, of course, that’s ordering the items by title in a descending fashion.

Disabled State

It’s possible to disable the control when interaction is not allowed:


<ComboBoxListItemPicker
  listId={listId}
  columnInternalName='Title'
  keyColumnInternalName='ID'
  disabled={true}
  onSelectedItem={this._onDisabledSelectionChanged}
  webUrl={context.pageContext.web.absoluteUrl}
  spHttpClient={context.spHttpClient as any}
  label={strings.DisabledPicker}
  suggestionsHeaderText={strings.PickerDisabled}
  noResultsFoundText={strings.PickerIsDisabled}
/>
Enter fullscreen mode Exit fullscreen mode

In short, it’s enough to set the disabled property to true to automatically apply a different styling and disable the possibility to interact with the control instance:


disabled={true}
Enter fullscreen mode Exit fullscreen mode

Conclusions

In my opinion, the ComboBoxListItemPicker control is an excellent solution for scenarios requiring SharePoint list item selection with a modern, user-friendly interface. It effectively combines the familiarity of a combobox with powerful SharePoint integration capabilities. The control’s support for filtering, ordering, and multiple selection modes makes it suitable for a wide range of applications.

If you’re interested in learning more, you can check the official documentation here.

Hope this helps!

Top comments (0)