SPFx and Property Pane

One of the most useful features of SPFx is the property pane , which allows end-users to configure web parts with several properties.

The property pane has three key metadata: a page, an optional header, and at least one group.

Pages provide you the flexibility to separate complex interactions and put them into one or more pages. Pages contain a header and groups.

Headers allow you to define the title of the property pane page.

Groups allow you to define the various sections or fields for the property pane through which you want to group your field sets.

In this blog post, we will explore how to use the property pane, as usual first let’s see the result and then the code.

This is the resulting not configured web part:

This is the the resulting situation with the web part and the property pane both open:

The property pane in detail not configured and configured:

Configuring the entries in the property pane updates the properties in the web part:

Now that we have an idea of the resulting UI let’s see the code in detail.

The code

After creating a web part solution using the Yeoman generator @microsoft/sharepoint you’ll have a web part with a default property description that can be configured in the property pane.

Following the already existing code we have to define the web part properties that we want to be configured in the property pane, in this sample named PropertyPaneSample (yep, no imagination) we have five different properties to show a few of the controls that can be used in the property pane, to do so in the IPropertyPaneSampleWebPartProps I defined the following:

export interface IPropertyPaneSampleWebPartProps {
  description: string;
  checkboxValue: boolean;
  dropdownValue: string;
  toggleValue: boolean;
  sliderValue: number;
}

To define the content of the property pane you have to use the method getPropertyPaneConfiguration inside of the {Your web part name}WebPart.ts file, in the sample the name is PropertyPaneSampleWebPart.ts. The getPropertyPaneConfiguration returns an object composed, as written in the post introduction, by an array of pages and each page is composed of a property header which contains the description of the page and a property groups which is an array of objects composed mainly of the groupName and groupFields properties.

protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
  return {
    pages: [
      {
        header: {
      description: strings.PropertyPaneDescription,
        },
    groups: [
      {
            groupName: strings.BasicGroupName,
            groupFields: [
              // omitted for brevity
            ],
      },
        ],
      },
    ],
  };
}

The groupName is fairly clear that is a string containing the group name.

The groupFields contains all the fields that we want to configure in the group.

In the sample the groupFields properties contains the various controls that we use to configure the web part, the content of the property is the following:

PropertyPaneTextField("description", {
    label: strings.DescriptionFieldLabel,
}),
PropertyPaneCheckbox("checkboxValue", {
    text: strings.CheckboxValueFieldLabel,
    checked: this.properties.checkboxValue,
}),
PropertyPaneDropdown("dropdownValue", {
    label: strings.DropdownValueFieldLabel,
    options: [
        { key: "1", text: "One" },
        { key: "2", text: "Two" },
        { key: "3", text: "Three" },
        { key: "4", text: "Four" },
        { key: "5", text: "Five" },
    ],
}),
PropertyPaneToggle("toggleValue", {
    label: strings.ToggleValueFieldLabel,
    onText: "On",
    offText: "Off",
    checked: this.properties.toggleValue,
}),
PropertyPaneSlider("sliderValue", {
    label: strings.SliderValueFieldLabel,
    min: 0,
    max: 100,
    step: 1,
    showValue: true,
    value: 50,
}),

As you can see we have some helper methods that create a specific control in our property pane, the names are esplicative but to be clear here is a clarification:

• PropertyPaneTextField: displays a text box.
• PropertyPaneCheckbox: displays a checkbox.
• PropertyPaneDropdown: displays a dropdown control where you have to define which are the possible selectable options.
• PropertyPaneToggle: displays a toggle where you can also define the labels for the on or off state.
• PropertyPaneSlider: displays a slider, you can specify properties such as the min and max supported values and also the step of the slider.

Once that you have set up your property pane you can now pass the configuration properties into the implementation of your web part control. In the sample solution I passed all the properties to the control class inside the render method of the PropertyPaneSampleWebPart class:

public render(): void {
  const element: React.ReactElement<IPropertyPaneSampleProps> =
  React.createElement(PropertyPaneSample, {
    description: this.properties.description,
    checkboxValue: this.properties.checkboxValue,
    dropdownValue: this.properties.dropdownValue,
    toggleValue: this.properties.toggleValue,
    sliderValue: this.properties.sliderValue,
  });

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

Inside the PropertyPaneSample control I simply display the values to have a visual representation of the changes.

So this is how to use the property pane to configure your web part!

If you want to discover more regarding the default property pane controls of SPFx you can check the official documentation here, it’s also worth mentioning that PnP have it’s own custom controls for the property pane, if you’re interested follow this link to check the official documentation, I recommend to have a look at all the available controls to avoid writing a custom one that maybe already exists.

If you want to check the sample solution I made for this post you can check it here.

Hope that helps!