Getting Started with the SharePoint Framework Property Pane

Introduction

One of the first concepts every SharePoint Framework (SPFx) developer should understand is the Property Pane.

The Property Pane provides a simple and standardized way for users to configure a web part without modifying its source code. Every value entered by the user is automatically stored by the framework and made available to the web part during rendering.

In this first example, we’ll build a very simple configurable web part with only two properties:

Title
Text

Although the example is intentionally simple, it introduces the complete data flow that every SPFx web part follows.

How the Property Pane Works

The process is surprisingly straightforward.

			
User
   │
   ▼
Property Pane
   │
   ▼
this.properties
   │
   ▼
React Component (Props)
   │
   ▼
Rendered HTML

		

Whenever the user changes a value in the Property Pane:

SPFx updates the this.properties object.
The web part executes the render() method again.
The React component receives the updated values as props.
React re-renders the UI.

No manual refresh is required.

Step 1 – Create the Web Part Properties

The first step is defining which properties your web part will expose.

			
export interface IPropertyPaneBasicWebPartProps {
  title: string;
  text: string;
}

These properties become part of the web part configuration and are persisted automatically by SharePoint.

Step 2 – Create the React Component Properties

The React component also needs to know which values it expects to receive.

			
export interface IPropertyPaneBasicProps {
  title: string;
  text: string;
}

Notice that both interfaces contain the same fields.

Although they look identical in this example, they represent different responsibilities:

Web Part Props → configuration stored by SharePoint.
React Props → data consumed by the React component.

Keeping these responsibilities separate makes larger solutions easier to maintain.

Step 3 – Pass the Properties to React

Inside the web part’s render() method, pass the values stored in this.properties to the React component.

			
const element: React.ReactElement<IPropertyPaneBasicProps> =
  React.createElement(PropertyPaneBasic, {
    title: this.properties.title,
    text: this.properties.text
  });
ReactDom.render(element, this.domElement);

		

This is the bridge between the SharePoint Framework and React.

Step 4 – Display the Values

The React component simply renders the received values.

			
import * as React from 'react';
import { IPropertyPaneBasicProps } from './IPropertyPaneBasicProps';
const PropertyPaneBasic: React.FC<IPropertyPaneBasicProps> = (props) => {
  return (
    <div>
      <h1>{props.title}</h1>
      <p>{props.text}</p>
    </div>
  );
};
export default PropertyPaneBasic;

		

At this point, the component has no knowledge of the Property Pane.

It simply receives props, exactly as any standard React component would.

Step 5 – Create the Property Pane

Now expose both fields to the user.

			
protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
  return {
    pages: [
      {
        header: {
          description: "Configuration"
        },
        groups: [
          {
            groupName: "Content",
            groupFields: [
              PropertyPaneTextField('title', {
                label: 'Title'
              }),
              PropertyPaneTextField('text', {
                label: 'Text'
              })
            ]
          }
        ]
      }
    ]
  };
}

		

The most important detail is the property name.

PropertyPaneTextField('title', ...)

The string "title" matches the property defined earlier.

			
'title'
        │
        ▼
this.properties.title

The same happens for "text".

Understanding `this.properties`

Many beginners wonder where this.properties comes from.

The answer is simple:

The SharePoint Framework automatically creates and manages this object for every web part.

Whenever a user modifies the Property Pane, SPFx updates the corresponding property automatically.

For example:

			
Property Pane
Title = My First SPFx Web Part
↓
this.properties.title
↓
"My First SPFx Web Part"

		

There is no need to manually save or retrieve these values.

React Doesn’t Know About the Property Pane

An important architectural detail is that React is completely unaware of the Property Pane.

React only receives normal props.

			
SharePoint Framework
        │
        ▼
this.properties
        │
        ▼
React Props
        │
        ▼
Component

		

This separation keeps your React components reusable and independent from the SharePoint Framework.

Why This Design Is Important

As your solution grows, your web part may expose many configuration options.

For example:

Display mode
Colors
List selection
Site selection
User selection
Taxonomy terms
Images
Files
API endpoints

All of these values follow exactly the same pattern introduced in this simple example.

Once you understand this flow, learning more advanced Property Pane controls becomes much easier.

What’s Next?

The built-in SharePoint Property Pane provides several standard controls, including:

Text fields
Dropdowns
Checkboxes
Toggle switches
Sliders
Choice groups

However, many real-world projects require richer configuration experiences.

This is where the PnP SPFx React Controls Property Controls become extremely valuable.

They provide ready-to-use controls such as:

Site Picker
List Picker
People Picker
Taxonomy Picker
File Picker
Folder Picker
Color Picker
Collection Data Editor
Markdown Editor

These controls dramatically reduce development time while providing a much richer configuration experience.

They will be explored in future articles.

Conclusion

Although this example only displays a title and a paragraph, it demonstrates the complete lifecycle of a configurable SPFx web part.

Understanding how the Property Pane, this.properties, and React props work together is one of the most important concepts in SharePoint Framework development.

Once this pattern becomes familiar, you’ll find that every configurable SPFx web part follows exactly the same architecture.