SPFx ModernTaxonomyPicker Control – Basic Example

Introduction

The ModernTaxonomyPicker control from @pnp/spfx-controls-react allows users to select one or more taxonomy terms from a SharePoint Term Set.

This control is useful when an SPFx Web Part needs to work with managed metadata, such as categories, departments, document classifications, topics, business areas, or any other taxonomy structure managed in the SharePoint Term Store.

In this basic example, the Web Part renders a taxonomy picker that allows multiple term selections and logs the selected terms to the browser console.

Official Documentation

Control: ModernTaxonomyPicker

Official URL:

https://pnp.github.io/sp-dev-fx-controls-react/controls/ModernTaxonomyPicker/

Install the PnP React Controls Package

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

Component Props

Create or update the props interface file:

import { WebPartContext } from '@microsoft/sp-webpart-base';
export interface IModernTaxonomyPickerWpProps {
  context: WebPartContext;
}

React Component

File:

src/webparts/modernTaxonomyPickerWp/components/ModernTaxonomyPickerWp.tsx

Code:

import * as React from 'react';
import { IModernTaxonomyPickerWpProps } from './IModernTaxonomyPickerWpProps';
import { ModernTaxonomyPicker } from '@pnp/spfx-controls-react/lib/ModernTaxonomyPicker';
const ModernTaxonomyPickerWp: React.FC<IModernTaxonomyPickerWpProps> = ({ context }) => {
  const onTaxPickerChange: any = (terms: any[]) => {
    console.log('Terms', terms);
  };
  return (
    <ModernTaxonomyPicker
      allowMultipleSelections={true}
      termSetId=""
      panelTitle="Select Term"
      label="Taxonomy Picker"
      context={context}
      onChange={onTaxPickerChange}
    />
  );
};
export default ModernTaxonomyPickerWp;

Web Part Render Method

In the Web Part file, make sure the SPFx context is passed to the React component:

public render(): void {
  const element: React.ReactElement<IModernTaxonomyPickerWpProps> = React.createElement(
    ModernTaxonomyPickerWp,
    {
      context: this.context
    }
  );
  ReactDom.render(element, this.domElement);
}

Important Configuration

The property below must receive the ID of an existing Term Set from your SharePoint Term Store:

termSetId=""

Example:

termSetId="f233d4b7-68fb-41ef-8b58-2af0bafc0d38"

Without a valid Term Set ID, the picker will not have a taxonomy source to display.

Code Explanation

The component imports ModernTaxonomyPicker from the official PnP React Controls package.

The allowMultipleSelections property enables the selection of more than one term.

The termSetId property identifies which Term Set will be used by the picker.

The panelTitle property defines the title displayed in the picker panel.

The label property defines the label shown above the control.

The context property passes the SPFx Web Part context to the control.

The onChange event is used to capture the selected terms. In this basic version, the selected terms are written to the browser console.

Basic Test

After adding a valid Term Set ID, run the SPFx solution:

heft start

Open the SharePoint Workbench, add the Web Part, open the picker, select one or more terms, and check the browser console.

You should see the selected terms logged as:

Terms [...]

Conclusion

This first version of the ModernTaxonomyPicker Web Part is intentionally simple. It focuses only on rendering the control, connecting it to the SPFx context, selecting terms from a Term Set, and capturing the selected values through the onChange event.

This is a good foundation before evolving the example to store selected taxonomy values, pre-load existing terms, or integrate the selected terms with SharePoint list metadata.