SPFx PropertyPaneToggle: Enabling and Disabling Features with a Toggle Switch

Introduction

The SharePoint Framework provides several native controls for building intuitive Property Panes. One of the most common is the PropertyPaneToggle.

Although it is similar to the PropertyPaneCheckbox, the Toggle has a different purpose.

A checkbox usually represents whether an option is selected.

A toggle represents whether a feature is enabled or disabled.

For this reason, Toggle controls are commonly used for configuration settings that activate or deactivate functionality.

Examples include:

• Enable Search
• Enable Pagination
• Show Header
• Enable Dark Mode
• Display Footer
• Enable Caching

In this article, we’ll build a simple example that allows users to enable or disable a feature.

What We Are Building

Our Web Part will expose a single boolean property.

enableFeature: boolean;

The Property Pane will contain a Toggle.

When the user switches it on or off, the Web Part will immediately display the current status.

Defining the Web Part Property

The Web Part stores the configuration using a boolean property.

export interface IPropertyPaneToggleWebPartProps {
    enableFeature: boolean;
}

Since this property is a boolean, it can only contain two values:

• true
• false

React Component Properties

The React component receives exactly the same property.

export interface IPropertyPaneToggleWpProps {
    enableFeature: boolean;
}

Notice that React has no knowledge of the Property Pane.

It simply receives a property.

Passing the Property to React

Inside the Web Part’s render() method:

const element: React.ReactElement<IPropertyPaneToggleWpProps> =
React.createElement(
    PropertyPaneToggleWp,
    {
        enableFeature: this.properties.enableFeature
    }
);
ReactDom.render(element, this.domElement);

This creates the bridge between SharePoint Framework and React.

Property Pane
      │
      ▼
this.properties.enableFeature
      │
      ▼
props.enableFeature

React Component

Our React component simply displays the current status.

import * as React from 'react';
import { IPropertyPaneToggleWpProps } from './IPropertyPaneToggleWpProps';
const PropertyPaneToggleWp: React.FC<IPropertyPaneToggleWpProps> = (props) => {
    return (
        <div>
            <h1>Property Pane Toggle</h1>
            <p>
                Feature Status:
                <strong>
                    {props.enableFeature ? " Enabled" : " Disabled"}
                </strong>
            </p>
        </div>
    );
};
export default PropertyPaneToggleWp;

Understanding the Ternary Operator

This line deserves special attention.

props.enableFeature ? "Enabled" : "Disabled"

This is called the ternary operator.

It is equivalent to writing:

if (props.enableFeature) {
    return "Enabled";
}
else {
    return "Disabled";
}

It is one of the most common patterns in React applications.

Creating the Toggle

The Property Pane configuration is very simple.

PropertyPaneToggle('enableFeature', {
    label: 'Enable Feature',
    onText: 'Enabled',
    offText: 'Disabled'
})

The first parameter

'enableFeature'

connects the Toggle to

this.properties.enableFeature

When the user changes the Toggle, SPFx automatically updates the property.

Understanding onText and offText

Unlike the Checkbox, the Toggle allows us to customize the labels displayed beside the switch.

onText: 'Enabled'

Displayed when the Toggle is ON.

offText: 'Disabled'

Displayed when the Toggle is OFF.

These labels make the configuration much clearer for users.

Setting a Default Value

When a Web Part is added to a page for the first time, the property may be undefined.

A simple solution is to initialize it inside onInit().

protected onInit(): Promise<void> {
    this.properties.enableFeature ??= true;
    return super.onInit();
}

The nullish assignment operator (??=) means:

Assign true only if the property is currently null or undefined.

After the user changes the value, SharePoint persists the configuration automatically.

Property Flow

The complete flow is:

Toggle
↓
enableFeature
↓
this.properties.enableFeature
↓
render()
↓
props.enableFeature
↓
React Component

This architecture is identical for every native Property Pane control.

Toggle vs Checkbox

Many beginners wonder whether they should use a Toggle or a Checkbox.

Although both return a boolean value, they communicate different intentions.

A simple rule is:

Use Checkbox when asking:

“Should this option be selected?”

Use Toggle when asking:

“Should this feature be enabled?”

The Toggle generally provides a more modern and intuitive experience for configuration settings.

Common Scenarios

PropertyPaneToggle is commonly used for:

• Enable Search
• Show Header
• Show Footer
• Enable Animations
• Enable Pagination
• Enable Dark Theme
• Enable Caching
• Enable Notifications

Any configuration that represents an ON/OFF state is a good candidate.

Why This Example Matters

This example introduces another important React pattern.

Instead of displaying:

true

or

false

the UI displays meaningful information:

Feature Status: Enabled

This greatly improves the user experience and makes the interface easier to understand.

Conclusion

The PropertyPaneToggle is one of the most frequently used native controls in SharePoint Framework.

It provides an intuitive way to enable or disable features while maintaining the same Property Pane architecture introduced in previous examples.

Although it stores exactly the same type of value as a Checkbox (boolean), its visual representation communicates a different meaning and often results in a better user experience.

Understanding when to use a Checkbox and when to use a Toggle is an important design decision for every SPFx developer.

References

SharePoint Framework Overview

Integrate with the Property Pane

PropertyPaneToggle API

IPropertyPaneToggleProps API

React Documentation