SharePoint client-side web part configurable properties in Property Pane using spfx

This SharePoint framework tutorial explains, how to work with configurable properties in Property Pane using spfx with typescript in SharePoint Online Office 365.

SharePoint client-side web part configurable properties in Property Pane using spfx with typescript

In the SPFx, web part properties are referred to as property panes. They allow controlling the behavior and appearance of a web part. The property pane allows end-users to configure the web part with several properties. It has three key metadata: a page, an optional header, and at least one group.

  • Page: It contains a header and groups. It provides the flexibility to separate complex interactions and put them into one or more pages.
  • Header: It allows you to define the title of the property pane.
  • Group: It allows you to define the various sections or fields for the property pane through which you want to group your field sets.

Following the Property pane field types:

  • Button
  • Checkbox
  • Choice group
  • Dropdown
  • Horizontal rule
  • Label
  • Link
  • Slider
  • Textbox
  • Multi-line Textbox
  • Toggle
  • Custom

Import property pane field types before you can use them in your code:

import {
   IPropertyPaneConfiguration,
   PropertyPaneTextField,
   PropertyPaneLabel,
   PropertyPaneToggle,
   PropertyPaneDropdown,
   PropertyPaneCheckbox, 
   PropertyPaneLink, 
   PropertyPaneSlider
 } from '@microsoft/sp-property-pane';

The property pane has two interaction modes:

  • Reactive: In Reactive, automatically updates the web part with the new values.
  • Non-reactive: Non-reactive does not update the web part automatically unless the user confirms the changes.

To turn on the non-reactive mode, add the following code in your web part:

protected get disableReactivePropertyChanges(): boolean {
     return true;
     }

When you add the above code in your web part, you will get the “Apply” button in the Property Pane as shown below.

sharepoint framework introduction to web part property pane
sharepoint framework introduction to web part property pane

We can also create multiple pages in the property pane. let’s see how we can create pages in getPropertyPaneConfiguration method.

sharepoint framework web part property pane
sharepoint framework web part property pane

When you create pages in your web part, you will get page buttons “Back and Next” in the Property Pane as shown below. For the next page click on “Next” Button and going back to previous page click on the “Back” button.

spfx clientside webpart with webpart properties
spfx clientside webpart with webpart properties

The following figure shows an example of a property pane in SharePoint. This is out put of our property pane creation example which we are going to do now.

sharepoint framework custom property pane
sharepoint framework custom property pane

In this example we are going to use property pane fields are PropertyPaneTextField, PropertyPaneLabel, PropertyPaneToggle, PropertyPaneDropdown, PropertyPaneCheckbox, PropertyPaneLink, PropertyPaneSlider.

In the Page one, PropertyPaneTextField, PropertyPaneLabel, PropertyPaneDropdown, PropertyPaneCheckbox, PropertyPaneLink,

In the Page Two, PropertyPaneToggle, PropertyPaneSlider

Create Property pane using SPFx with Typescript

Create SPFx Solution:

Step 1: Create a new Solution for example “PropertyPane ”

  • Open the command prompt. Create a directory for SPFx solution.
    • md PropertyPane
  • Navigate to the above-created directory
    • cd PropertyPane

Step 2: Run Yeoman SharePoint Generator to create the solution.

  • yo @microsoft/sharepoint

Yeoman generator will present you with the wizard by asking questions about the solution to be created.

  • Solution Name: Hit Enter to have a default name (
    PropertyPane in this case) or type in any other name for your solution.
  • Target for component: Here, we can select the target environment where we are planning to deploy the client web-part; i.e., Selected choice – SharePoint Online only (latest)
  • Place of files: Selected choice – use current folder.
  • Deployment option: Selecting Y will allow the app to be deployed instantly to all sites and will be accessible everywhere. Selected choice – N (install on each site explicitly)
  • Type of client-side component to create: Choose the web-part option. Select option – Web-part.
  • Web part name: Hit enter to select the default name or type in any other name. Type name – propertyPane
  • Web part description: Hit enter to select the default description or type in any other value.
  • Framework to use: Select option – No JavaScript Framework.

At this point, Yeoman installs the required dependencies and scaffolds the solution files along with the propertyPane web part. This might take a few minutes.

When the scaffold is complete, you should get a Successful message.

Step 3: In the command prompt type the below command to open the solution in vs code editor-> ” code .

sharepoint framework property pane controls
sharepoint framework property pane controls

Step 4: Go to the “propertyPaneWebpart.ts” file, copy and paste the below code.

import { Version } from '@microsoft/sp-core-library';
import { BaseClientSideWebPart 

} from '@microsoft/sp-webpart-base';
import {
  IPropertyPaneConfiguration,
  PropertyPaneTextField,
  PropertyPaneLabel,
  PropertyPaneToggle,
  PropertyPaneDropdown,
  PropertyPaneCheckbox, 
  PropertyPaneLink, 
  PropertyPaneSlider
} from '@microsoft/sp-property-pane';
import { escape } from '@microsoft/sp-lodash-subset';

import styles from './PropertyPaneWebPart.module.scss';
import * as strings from 'PropertyPaneWebPartStrings';

export interface IPropertyPaneWebPartProps {
  [x: string]: any;
  description: string;
}

export default class PropertyPaneWebPart extends BaseClientSideWebPart<IPropertyPaneWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div class="${ styles.propertyPane }">
        <div class="${ styles.container }">
          <div class="${ styles.row }">
            <div class="${ styles.column }">
              <span class="${ styles.title }">Welcome to SharePoint!</span>
              <p class="${ styles.subTitle }">Customize SharePoint experiences using Web Parts.</p>
              <p class="${ styles.description }">${escape(this.properties.description)}</p>
              <p class="${ styles.description }">CustomFiled:${escape(this.properties.textboxField)}</p>
              <p class="${ styles.description }">dropdown:${escape(this.properties.DropdownField)}</p>
              <p class="${ styles.description }">Toggle:${escape(this.properties.propertyToggle)}</p>
              <p class="${ styles.description }">Property Checkbox:${escape(this.properties.propertyCheckbox)}</p>
              <p class="${ styles.description }">Property Slider:${escape(this.properties.propertySlider)}</p>
              <a href="https://aka.ms/spfx" class="${ styles.button }">
                <span class="${ styles.label }">Learn more</span>
              </a>
            </div>
          </div>
        </div>
      </div>`;
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }

  protected get disableReactivePropertyChanges(): boolean {
    return true;
    }
   
  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    let templateProperty: any;
    if (this.properties.propertyToggle) {
      templateProperty = PropertyPaneTextField('propertyOn', {
        label: 'Property Textbox shown when toggle is turned on'
      });
    } else {
      templateProperty = PropertyPaneDropdown('propertyOff', {
        label: 'Property Dropdown shown when toggle is turned off',
        options: [{key: "One", text: "One"}, {key: "Two", text: "Two"}]
      });
    }

    return {
      pages: [
        {
          header: {
            description: 'Page-1'
          },
          groups: [
            {
              groupName: strings.BasicGroupName,
              groupFields: [
                PropertyPaneTextField('description', {
                  label: strings.DescriptionFieldLabel
                })
              ]
            },
            {
              groupName: "Custom group",
              groupFields: [
              PropertyPaneTextField('textboxField', {
              label: "Enter a custom value"
              }),
              PropertyPaneLabel('labelField', {
                text: "This is a custom text in PropertyPaneLabel"
                }),
                PropertyPaneDropdown('DropdownField', {
                 label:"Select Dropdown",
                 options: [{key: "New", text: "New"}, {key: "Pending", text: "Pending"},{key: "Approve", text: "Approve"} ]
                }),
                
                
                PropertyPaneCheckbox('propertyCheckbox', {
                  text: 'yes/no'
                  
                }),
                PropertyPaneLink('propertyLink', {
                  text: 'Gmail',href:'https://gmail.com', target:'_blank'
                  
                }),
                
              ]
              }
              
          ]
        },
        {
          header: {
            description:'page-2'
            
          },
          groups: [
            
            {
              groupName: "Custom Group-2",
              groupFields: [
                PropertyPaneToggle('propertyToggle', {
                  label: 'Property toggle'
                }),
                templateProperty,
                PropertyPaneSlider('propertySlider', {
                  label:'slider', min:1,max:5
                  
                }),
            ]
            }
          ]
        }        
      ]
    };
  }
}

Step 5: On the command prompt type “gulp serve”. Next, go to SharePoint workbench in our site(https://Your-Domain-Name/sites/SiteCollection/_layouts/15/Workbench.aspx), add our preoprtyPane web part.

sharepoint framework clientside webparts nonreactive property pane
sharepoint framework clientside webparts nonreactive property pane

Step 6: Edit web part to modify property fields on page one.

sharepoint framework client side web parts nonreactive property pane
sharepoint framework client side web parts nonreactive property pane

Step 7: Click the Next button to see fields in the next page and modify the fields then click on the “Apply” button.

spfx client side web part properties
spfx client side web part properties

You may also like following SharePoint Framework tutorials:

This SharePoint framework tutorial explains, how to create property pane in SharePoint Framework (SPFx). Property panes allow easy configuration of SPFx client-side web part. Properties can be grouped by the pages in SharePoint.

  • Hi are we able to create a property pane once and share it across multiple web parts? I want the user to be able to set a border property for each web part but I don’t want to repeat that code multiple tmes…any idea?

  • Great article! No discussion of Property Pane is complete without mentioning the the open source PnP community has created several advanced controls for the property pane. e.g., PeoplePicker, List Selector, etc. Completely free. Just install, import, and use. https://pnp.github.io/sp-dev-fx-property-controls/

  • >