SPFx PropertyPaneDropdown: Creating Selection Lists in the Property Pane

Introduction

One of the most frequently used controls in the SharePoint Framework Property Pane is the PropertyPaneDropdown.

Unlike a text field, a dropdown allows users to select one option from a predefined list. This reduces typing errors, improves consistency, and provides a better configuration experience.

Typical use cases include:

• selecting a theme;
• choosing a layout;
• selecting a language;
• choosing a display mode;
• selecting colors;
• choosing predefined options.

In this article, we’ll build a simple example that allows the user to choose a color from a dropdown list.

What We Are Building

Our web part will expose one property:

selectedColor: string;

The user will choose one of three options:

• Red
• Green
• Blue

The selected value will be displayed inside the web part.

Web Part Property

The configuration property is defined as:

export interface IPropertyPaneDropdownWebPartProps {
  selectedColor: string;
}

This property is automatically managed by SPFx.

React Component Props

The React component receives exactly the same value.

export interface IPropertyPaneDropdownWpProps {
  selectedColor: string;
}

Passing the Property to React

Inside the render() method:

const element: React.ReactElement<IPropertyPaneDropdownWpProps> =
  React.createElement(
    PropertyPaneDropdownWp,
    {
      selectedColor: this.properties.selectedColor
    }
  );
ReactDom.render(element, this.domElement);

This creates the bridge between SPFx and React.

React Component

The component simply renders the selected value.

import * as React from 'react';
import { IPropertyPaneDropdownWpProps } from './IPropertyPaneDropdownWpProps';
const PropertyPaneDropdownWp: React.FC<IPropertyPaneDropdownWpProps> = (props) => {
  return (
    <div>
      <h1>Property Pane Dropdown</h1>
      <p>Selected Color: {props.selectedColor}</p>
    </div>
  );
};
export default PropertyPaneDropdownWp;

Notice that React has no idea where the value comes from.

It simply receives a property called:

props.selectedColor

Creating the Dropdown

The Property Pane configuration looks like this.

PropertyPaneDropdown('selectedColor', {
  label: 'Select a Color',
  options: [
    { key: 'red', text: 'Red' },
    { key: 'green', text: 'Green' },
    { key: 'blue', text: 'Blue' }
  ]
})

This introduces two new concepts:

• options
• key

Understanding the Options Collection

The dropdown displays a collection of options.

options: [
  { key: 'red', text: 'Red' },
  { key: 'green', text: 'Green' },
  { key: 'blue', text: 'Blue' }
]

Each option has two properties.

key

key: 'red'

This is the value stored by SharePoint.

text

text: 'Red'

This is what the user sees.

For example, if the user selects:

Green

The Property Pane stores:

this.properties.selectedColor = "green";

Not:

"Green"

This distinction is extremely important because many SPFx controls work exactly the same way.

The Property Flow

The complete flow is:

Dropdown
     │
     ▼
selectedColor
     │
     ▼
this.properties.selectedColor
     │
     ▼
React Props
     │
     ▼
props.selectedColor

Every time the user changes the dropdown, SPFx updates the property, executes render(), and React displays the new value.

Why Use a Dropdown?

A dropdown is preferable when users must choose from a known set of values.

Advantages include:

• no typing mistakes;
• consistent configuration;
• easier validation;
• simpler code;
• better user experience.

Dropdown vs TextField

Common Scenarios

A dropdown is commonly used for:

• Theme selection
• Display mode
• Language
• Sort order
• Chart type
• Layout selection
• Status filters

Conclusion

PropertyPaneDropdown is one of the most useful native Property Pane controls.

Besides introducing selection lists, it also teaches an important SPFx concept: every displayed option has a key and a text.

Understanding this pattern will make it much easier to work with more advanced controls, including many Property Controls from the PnP library.

References

SharePoint Framework overview

Property Pane documentation

PropertyPaneDropdown API

IPropertyPaneDropdownOption

React Documentation