PropertyFieldMultiSelect – Allow Multiple Selections in the SPFx Property Pane

One of the most useful controls available in the PnP SPFx Property Controls library is PropertyFieldMultiSelect. It allows users to select multiple values from a predefined list directly in the Web Part Property Pane.

Unlike the native SharePoint Property Pane controls, this control provides a much more convenient multi-selection experience without requiring additional custom development.

What is PropertyFieldMultiSelect?

PropertyFieldMultiSelect displays a list of options where users can select one or more items.

The selected values are automatically stored in a string array (string[]) inside the Web Part properties.

Typical scenarios include:

• Categories
• Document types
• Departments
• Tags
• Available features
• Display options

Official Documentation

Install the library

npm install @pnp/spfx-property-controls --save

Import the control

import {
  PropertyFieldMultiSelect
} from '@pnp/spfx-property-controls/lib/PropertyFieldMultiSelect';

Create the Web Part property

The selected values are stored as a string array.

export interface IPropertyFieldMultiSelectWpWebPartProps {
  description: string;
  multiSelect: string[];
}

Initialize the property

To avoid undefined values during the first execution, initialize the property inside onInit().

protected onInit(): Promise<void> {
  this.properties.multiSelect ??= [];
  return this._getEnvironmentMessage().then(message => {
    this._environmentMessage = message;
  });
}

Add the control to the Property Pane

PropertyFieldMultiSelect('multiSelect', {
  key: 'multiSelect',
  label: 'Select Options',
  options: [
    {
      key: 'option1',
      text: 'Option 1'
    },
    {
      key: 'option2',
      text: 'Option 2'
    },
    {
      key: 'option3',
      text: 'Option 3'
    }
  ],
  selectedKeys: this.properties.multiSelect
})

Understanding the properties

key

Unique identifier of the Property Control.

key: 'multiSelect'

label

Displayed above the control.

label: 'Select Options'

options

Defines the available choices.

options: [
  {
    key: 'option1',
    text: 'Option 1'
  },
  {
    key: 'option2',
    text: 'Option 2'
  },
  {
    key: 'option3',
    text: 'Option 3'
  }
]

Each option contains:

selectedKeys

Represents the currently selected items.

selectedKeys: this.properties.multiSelect

Notice that this property expects a string array.

Accessing the selected values

The values are available like any other Web Part property.

this.properties.multiSelect

Example:

[
  "option1",
  "option3"
]

Passing the values to the React component

const element = React.createElement(
  PropertyFieldMultiSelectWp,
  {
    multiSelect: this.properties.multiSelect,
    description: this.properties.description,
    environmentMessage: this._environmentMessage,
    isDarkTheme: this._isDarkTheme,
    userDisplayName: this.context.pageContext.user.displayName
  }
);

Displaying the selected values

<p>
  Selected options:
  {
    props.multiSelect.length > 0
      ? props.multiSelect.join(', ')
      : ' No options selected'
  }
</p>

Example output:

Selected options:
Option1, Option3

Common mistake

A frequent error is trying to use:

multiSelect: this.properties.multiSelect

inside the Property Control configuration.

This generates the TypeScript error:

Object literal may only specify known properties,
and 'multiSelect' does not exist in type
'IPropertyFieldMultiSelectProps'

The correct property name is:

selectedKeys

Correct:

selectedKeys: this.properties.multiSelect

Complete Property Pane example

protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
  return {
    pages: [
      {
        groups: [
          {
            groupName: "Settings",
            groupFields: [
              PropertyPaneTextField('description', {
                label: 'Description'
              }),
              PropertyFieldMultiSelect('multiSelect', {
                key: 'multiSelect',
                label: 'Select Options',
                options: [
                  {
                    key: 'option1',
                    text: 'Option 1'
                  },
                  {
                    key: 'option2',
                    text: 'Option 2'
                  },
                  {
                    key: 'option3',
                    text: 'Option 3'
                  }
                ],
                selectedKeys: this.properties.multiSelect
              })
            ]
          }
        ]
      }
    ]
  };
}

Advantages

• Native integration with the SPFx Property Pane
• Multiple selections without custom controls
• Strong TypeScript typing
• Easy binding to Web Part properties
• Automatic persistence
• Lightweight and easy to configure

When to use PropertyFieldMultiSelect

This control is ideal when users need to configure one or more values from a predefined list, such as:

• Categories
• Departments
• Languages
• Features
• Enabled modules
• File types
• Regions
• Display options

Conclusion

PropertyFieldMultiSelect is an excellent replacement for creating custom multi-selection interfaces in the SharePoint Property Pane. It provides a clean user experience, integrates naturally with SPFx, and automatically persists the selected values as a string[].

The most common implementation mistake is using the property name multiSelect inside the control configuration. The correct property is selectedKeys, which binds the selected options to the Web Part property.

Once configured, the control requires very little code while delivering a flexible and intuitive configuration experience.

References

• PnP SPFx Property Controls Documentation
  https://pnp.github.io/sp-dev-fx-property-controls/
• PropertyFieldMultiSelect Documentation
  https://pnp.github.io/sp-dev-fx-property-controls/controls/PropertyFieldMultiSelect/
• SharePoint Framework Documentation
  https://learn.microsoft.com/sharepoint/dev/spfx/sharepoint-framework-overview
• Microsoft Fluent UI
  https://fluent2.microsoft.design/