SPFx PropertyPaneChoiceGroup: Using Radio Buttons in the Property Pane

Introduction

this.properties.selectedTheme = “dark”;

this.properties.selectedTheme = “dark”;

this.properties.selectedTheme = “dark”;

This makes it an excellent choice when the number of options is small.

In this article, we’ll build a simple example where the user selects a theme using a Choice Group.

What We Are Building

Our Web Part will expose a single property:

selectedTheme: string;

The user will be able to choose one of three options:

• Light
• Dark
• Auto

The selected option will then be displayed inside the Web Part.

Defining the Web Part Property

The property stored by SharePoint is defined as:

export interface IPropertyPaneChoiceGroupWebPartProps {
    selectedTheme: string;
}

Like every Property Pane control, the value is automatically stored inside this.properties.

Defining the React Props

The React component receives exactly the same property.

export interface IPropertyPaneChoiceGroupWpProps {
    selectedTheme: string;
}

Notice that the React component does not know anything about the Property Pane.

It only receives a string called selectedTheme.

Passing the Property to React

Inside the Web Part’s render() method:

const element: React.ReactElement<IPropertyPaneChoiceGroupWpProps> =
React.createElement(
    PropertyPaneChoiceGroupWp,
    {
        selectedTheme: this.properties.selectedTheme
    }
);

This line creates the connection between SharePoint Framework and React.

The value stored inside

this.properties.selectedTheme

becomes

props.selectedTheme

inside the React component.

React Component

The component is very simple.

import * as React from 'react';
import { IPropertyPaneChoiceGroupWpProps } from './IPropertyPaneChoiceGroupWpProps';
const PropertyPaneChoiceGroupWp: React.FC<IPropertyPaneChoiceGroupWpProps> = (props) => {
    return (
        <div>
            <h1>Property Pane Choice Group</h1>
            <p>
                Selected Theme: {props.selectedTheme}
            </p>
        </div>
    );
};
export default PropertyPaneChoiceGroupWp;

Every time the user changes the selected option, SPFx calls render() again and React receives the updated property.

Creating the Choice Group

The Property Pane configuration is straightforward.

PropertyPaneChoiceGroup('selectedTheme', {
    label: 'Select a Theme',
    options: [
        {
            key: 'light',
            text: 'Light'
        },
        {
            key: 'dark',
            text: 'Dark'
        },
        {
            key: 'auto',
            text: 'Auto'
        }
    ]
})

The first parameter:

'selectedTheme'

is the property name.

Whenever the user changes the selected option, SPFx updates:

this.properties.selectedTheme

automatically.

Understanding Key and Text

Each option contains two important properties.

{
    key: 'light',
    text: 'Light'
}

key

The value stored by SharePoint.

key: 'light'

text

The text shown to the user.

text: 'Light'

If the user clicks:

Dark

SPFx stores:

this.properties.selectedTheme = "dark";

Notice that the stored value is dark, not Dark.

This follows exactly the same behavior as the PropertyPaneDropdown.

How the Data Flows

The complete flow is:

Choice Group
↓
selectedTheme
↓
this.properties.selectedTheme
↓
render()
↓
props.selectedTheme
↓
React Component

This is exactly the same architecture used by every Property Pane control.

ChoiceGroup vs Dropdown

Many developers ask:

When should I use a Choice Group instead of a Dropdown?

Although both controls return the selected key, they offer different user experiences.

As a general recommendation:

• Use ChoiceGroup when you have between 2 and 4 options.
• Use Dropdown when the list becomes larger.

This provides a better user experience and reduces unnecessary clicks.

Common Scenarios

Choice Groups are commonly used for:

• Theme selection
• Display mode
• Card layout
• List or Grid view
• Sort order
• Light/Dark mode
• Language selection
• Feature activation modes

Whenever the user must select exactly one option and the number of choices is small, the Choice Group is usually the preferred control.

Why This Example Matters

This example reinforces an important concept introduced in previous articles.

The React component never interacts directly with the Property Pane.

Instead, the flow is always:

Property Pane
↓
this.properties
↓
render()
↓
React Props
↓
UI

Once you understand this architecture, learning additional Property Pane controls becomes much easier because they all follow the same design.

Conclusion

The PropertyPaneChoiceGroup is one of the simplest native controls provided by SPFx, yet it offers an excellent user experience when the number of available choices is small.

Although it shares the same data model as PropertyPaneDropdown, the presentation is very different.

Understanding when to use a dropdown and when to use radio buttons is an important design decision that helps build more intuitive SharePoint Web Parts.

In the next article, we’ll continue exploring the remaining native Property Pane controls before moving to the advanced Property Controls available in the PnP library.

References

SharePoint Framework Overview

Integrate with the Property Pane

PropertyPaneChoiceGroup API

IPropertyPaneChoiceGroupOption API

React Documentation