How to Add Custom Controls in SPFx Property Pane

When building SPFx web parts, the property pane is the primary way to let users configure how the web part behaves without touching any code. In one of our SharePoint Online projects, we needed to show list or library data directly on a modern page and still allow site owners to choose which list and how many items to display.

The best approach was to use SPFx custom property pane controls so users could pick a list or library, and then the web part would automatically render its data using PnP React controls.

In this step-by-step tutorial, you will learn how the default SPFx property pane works, how values flow from the pane into the web part, and then how to add PnP custom controls such as PropertyFieldListPicker to the property pane. Finally, you will see how to use the selected list ID in a React component to fetch list items via SPHttpClient and display them using the PnP ListView control.

Recently, one of my colleagues was working on a SharePoint site customization using SPFx. In this customization, we needed to add an SPFx web part to the SharePoint site page so people on the site can quickly see the latest details of a specific SharePoint list/library on the page itself, without navigating to each list in the site. We also needed to allow users to specify how many records they want to see in this web part.

The user could then select any list or library, and the web part would automatically show the default view of the selected list. To achieve this, we used custom controls in the SPFx property pane and passed the selected list/library to the web part. In this tutorial, you will see how to use custom controls in the SPFx web part property pane with a working example that displays list views.

Download Complete Solution

You can download the complete SPFx solution, unzip it, run npm i, and test it without changing any code. This helps you quickly understand how the custom property pane controls and PnP React controls are wired together

Note: This example uses lists and libraries from the current SharePoint site context; it does not cover cross-site list selection.

Scenario used in this demo

In this demo scenario:

• An SPFx web part displays items from a SharePoint list or library on a modern SharePoint page.
• The editor can pick the target list/library in the property pane using a custom list picker control.
• The selected list’s data is fetched using SPHttpClient and rendered using the PnP ListView React control.

SPFx Web Part Property Pane Overview

In the image for the basic example, you can see that for this web part, the “Description” field is on the property pane. The text entered in that field is displayed in the web part.

We use the property pane to configure the web part by passing dynamic values from the pane to the web part. Before adding custom controls, let’s understand how the default property pane control works and how it passes its value to the web part.

Basically, we used this property pane to configure the webpart by passing the dynamic value to the webpart.

Before we start adding custom controls to the SPFx web part property pane, let’s first understand the default property pane control and how it passes its value to the web part. You should already know how to create an SPFx web part using the React framework.

Step 1: Check the manifest.json file

Once you have created the SPFx web part, open the manifest.json file.

The manifest.json file contains basic information about the web part such as:

• Web part ID, alias, and componentType.
• The preconfiguredEntries section, which has a properties object that holds the default values for the web part.

When you add new custom controls to the property pane, you can define their default values in the properties object inside preconfiguredEntries.

When we add new custom controls to the property pane, we can define their default values here.

Step 2: Understand default PropertyPaneTextField

Now open the main web part .ts file. At the end of the class, you will find the getPropertyPaneConfiguration() method; this is where you configure property pane fields.

By default, there is a PropertyPaneTextField for the description. To use this control, you import it as shown below:

import {
  type IPropertyPaneConfiguration,
  PropertyPaneTextField
} from '@microsoft/sp-property-pane';

This code adds the description field to the web part property pane.

Step 3: Create props to pass values to React

To display the text entered in the description field in the property pane inside the web part, you need to create a prop and pass it to the React component. You will find the code below in the Props.ts file.

export interface IPropertyPaneDemoProps {
  description: string;
  isDarkTheme: boolean;
  environmentMessage: string;
  hasTeamsContext: boolean;
  userDisplayName: string;
}