Getting Started with PropertyFieldFolderPicker in SPFx

One of the most common requirements when building SharePoint Framework solutions is allowing users to select a document library folder directly from the Property Pane. Instead of asking users to manually type a URL, the PropertyFieldFolderPicker control from the PnP SPFx Property Controls library provides a friendly folder browser integrated with SharePoint.

In this article we’ll build a simple Web Part that allows the user to select a folder, store the selected value in the Web Part properties, and display the selected folder information on the page.

What is PropertyFieldFolderPicker?

PropertyFieldFolderPicker is a Property Pane control that displays a SharePoint folder picker inside the Web Part configuration panel.

It allows users to:

• Browse document libraries
• Navigate folder structures
• Select an existing folder
• Create new folders (optional)
• Persist the selected folder in the Web Part properties

Instead of working with strings, the control returns an IFolder object containing information about the selected folder.

Official documentation

PnP Property Controls Home

PropertyFieldFolderPicker

Installing the library

If your project does not already contain the PnP Property Controls package, install it first.

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

Then install dependencies.

npm install

Finally start the local development server.

heft start

Importing the control

Import the folder picker and its interface.

import {
  IFolder,
  PropertyFieldFolderPicker
} from '@pnp/spfx-property-controls/lib/PropertyFieldFolderPicker';

Web Part property

Store the selected folder as an IFolder.

export interface IPropertyFieldFolderPickerWpWebPartProps {
  description: string;
  folderPicker: IFolder;
}

Unlike many Property Pane controls that return strings or numbers, this control stores an object containing folder metadata.

Adding the Property Pane control

Inside getPropertyPaneConfiguration(), add the Folder Picker.

PropertyFieldFolderPicker('folderPicker', {
    context: this.context,
    properties: this.properties,
    onPropertyChange:
      this.onPropertyPaneFieldChanged.bind(this),
    key: 'folderPickerId',
    label: 'Folder Picker',
    selectedFolder: this.properties.folderPicker,
    canCreateFolders: true,
    rootFolder: {
        Name: 'Shared Documents',
        ServerRelativeUrl: '/Shared Documents'
    },
    onSelect: (folder: IFolder) => {
        this.properties.folderPicker = folder;
        this.render();
    }
})

Understanding each property

context

Provides the current SharePoint context required by the control.

context: this.context

properties

Allows the control to read and update Web Part properties.

properties: this.properties

onPropertyChange

Notifies SharePoint whenever the selected folder changes.

onPropertyChange:
this.onPropertyPaneFieldChanged.bind(this)

selectedFolder

Displays the previously selected folder when reopening the Property Pane.

selectedFolder:
this.properties.folderPicker

rootFolder

Defines where browsing starts.

rootFolder: {
    Name: 'Shared Documents',
    ServerRelativeUrl: '/Shared Documents'
}

A good practice is to build this URL dynamically.

rootFolder: {
    Name: 'Shared Documents',
    ServerRelativeUrl:
`${this.context.pageContext.web.serverRelativeUrl}/Shared Documents`
}

This makes the Web Part portable across sites.

canCreateFolders

Allows users to create folders while browsing.

canCreateFolders: true

If set to false, only existing folders can be selected.

onSelect

Called immediately after the user selects a folder.

onSelect: (folder: IFolder) => {
    this.properties.folderPicker = folder;
    this.render();
}

This is where you typically persist the selected folder and refresh the Web Part.

Displaying the selected folder

Inside the React component:

{
props.folderPicker ?
<>
<p><strong>Name:</strong>
{props.folderPicker.Name}</p>
<p><strong>Server Relative Url:</strong>
{props.folderPicker.ServerRelativeUrl}</p>
</>
:
<p>No folder selected.</p>
}

After selecting a folder, the Web Part immediately displays its information.

Understanding the IFolder object

The selected folder is returned as an IFolder object.

The most useful properties are:

folder.Name
folder.ServerRelativeUrl

Notice that Name starts with a capital letter.

This is a common mistake.

Incorrect:

folder.name

Correct:

folder.Name

Typical use cases

PropertyFieldFolderPicker is useful when your Web Part needs to:

• Upload files to a specific folder
• Read documents from a selected folder
• Display folder contents
• Monitor a document library folder
• Configure document processing
• Select an image repository
• Configure backup locations
• Work with approval folders

Advantages

Compared to asking users to manually enter a folder URL:

• No typing mistakes
• Better user experience
• Folder validation
• Easy navigation
• Optional folder creation
• Returns structured data
• Integrates naturally with SharePoint

Things to remember

• Import IFolder from @pnp/spfx-property-controls, not from the React Controls package.
• Use folder.Name, not folder.name.
• Build the rootFolder dynamically whenever possible.
• Store the returned IFolder object in your Web Part properties.
• Call this.render() after selection if you want the page to refresh immediately.

Conclusion

PropertyFieldFolderPicker is one of the most practical Property Pane controls available in the PnP SPFx Property Controls library. It removes the need for users to manually enter folder URLs, provides a familiar SharePoint browsing experience, and returns a strongly typed IFolder object that can be used throughout your Web Part.

Whether you’re building document management solutions, upload components, reporting tools, or content browsers, this control offers a simple and user-friendly way to configure folder-based behavior while keeping your code clean and strongly typed.

References

PnP SPFx Property Controls

PropertyFieldFolderPicker Documentation