PropertyFieldEnterpriseTermPicker – Browsing the SharePoint Term Store from the Property Pane

The PropertyFieldEnterpriseTermPicker is one of the most powerful controls available in the PnP SPFx Property Controls library. Unlike the standard PropertyFieldTermPicker, this control is designed to browse the Enterprise Managed Metadata Service (Term Store) and allows users to navigate through Groups, Term Sets, and Terms before making a selection.

It is the ideal choice when your solution needs to work with large corporate taxonomies shared across SharePoint Online.

What is the Enterprise Term Picker?

The control provides a complete browser for the SharePoint Online Term Store directly inside the Web Part Property Pane.

It allows the user to:

• Browse the Term Store hierarchy
• Navigate Groups
• Navigate Term Sets
• Select one or multiple Terms
• Display taxonomy labels
• Load taxonomy nodes on demand

Unlike the simpler Term Picker, this control was created specifically for Enterprise Metadata scenarios.

Official Documentation

PnP Property Controls

PropertyFieldEnterpriseTermPicker

Installation

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

After installing:

npm install

Run the project:

heft start

Import

import {
  IPickerTerms,
  PropertyFieldEnterpriseTermPicker
} from '@pnp/spfx-property-controls/lib/PropertyFieldEnterpriseTermPicker';

Property

export interface IPropertyFieldEnterpriseTermPickerWpWebPartProps {
    description: string;
    terms: IPickerTerms;
}

The selected terms are stored as an IPickerTerms collection.

Basic Property Pane Configuration

PropertyFieldEnterpriseTermPicker(
  'terms',
  {
    label: 'Select terms',
    panelTitle: 'Enterprise Term Picker',
    initialValues: this.properties.terms,
    allowMultipleSelections: true,
    excludeSystemGroup: false,
    onPropertyChange: this.onPropertyPaneFieldChanged,
    properties: this.properties,
    context: this.context as any,
    onGetErrorMessage: undefined,
    deferredValidationTime: 0,
    key: 'enterpriseTermPicker'
  }
)

Understanding each property

label

Displayed inside the Property Pane.

label: 'Select terms'

panelTitle

Title displayed in the picker dialog.

panelTitle: 'Enterprise Term Picker'

initialValues

Previously selected taxonomy terms.

initialValues: this.properties.terms

allowMultipleSelections

Allows selecting multiple taxonomy terms.

allowMultipleSelections: true

Or only one:

allowMultipleSelections: false

excludeSystemGroup

Controls whether the hidden System taxonomy group should appear.

excludeSystemGroup: true

Recommended for production environments.

includeLabels

Displays additional taxonomy labels.

includeLabels: true

deferredValidationTime

Delay before validation.

deferredValidationTime: 0

context

SPFx Web Part context.

context: this.context as any

Note

In SPFx 1.23 some projects may report a TypeScript incompatibility caused by duplicated Microsoft packages inside node_modules.

Using

context: this.context as any

is a safe workaround until package versions are aligned.

Restricting the picker

One of the nicest features is the ability to restrict what the user can browse.

Restrict by Group

limitByGroupNameOrID: 'Corporate Metadata'

Only this taxonomy group will be displayed.

Restrict by Term Set

limitByTermsetNameOrID: 'Departments'

Only this Term Set becomes available.

Restrict both

limitByGroupNameOrID: 'Corporate Metadata',
limitByTermsetNameOrID: 'Departments'

The picker becomes focused on a very specific taxonomy.

Showing the entire Term Store

If you remove both properties:

limitByGroupNameOrID
limitByTermsetNameOrID

the control allows navigation through the available Term Store hierarchy.

PropertyFieldEnterpriseTermPicker(
  'terms',
  {
      ...
      allowMultipleSelections: true,
      excludeSystemGroup: false,
      includeLabels: true
  }
)

This is usually the best configuration while exploring your tenant.

Reading the selected terms

The selected terms are returned as an IPickerTerms collection.

Example:

props.terms.map(term => (
    <li key={term.key}>
        {term.name}
    </li>
))

Each item contains useful information such as:

• Name
• Id
• Path
• Term Set
• Labels

Enterprise vs Term Picker

Performance

The Enterprise Term Picker does not download the entire Term Store.

Instead, it loads:

• Groups
• Term Sets
• Terms

only when the user expands each node.

This lazy-loading behavior keeps the Property Pane responsive even when the tenant contains thousands of taxonomy terms.

Common Issue (SPFx 1.23)

Some developers may encounter the following TypeScript error:

Type 'WebPartContext' is not assignable to type 'BaseComponentContext'

This is not caused by the PropertyFieldEnterpriseTermPicker itself.

Instead, it is usually related to duplicated versions of Microsoft SPFx packages inside node_modules, where two different definitions of BaseComponentContext are loaded by TypeScript.

A practical workaround is:

context: this.context as any

until all SPFx package versions are aligned.

When should I use this control?

Use PropertyFieldEnterpriseTermPicker when:

• Your organization uses Managed Metadata.
• You have multiple taxonomy groups.
• Users must browse the entire Term Store.
• You need enterprise-level taxonomy navigation.
• The taxonomy contains many Term Sets.

Final Thoughts

The PropertyFieldEnterpriseTermPicker is one of the most complete Property Controls available for SPFx. It transforms the standard Property Pane into a full Enterprise Taxonomy browser, allowing users to navigate large Managed Metadata hierarchies without writing custom dialogs.

Combined with SharePoint Managed Metadata, it provides a scalable, user-friendly way to configure taxonomy-driven solutions while benefiting from lazy loading and flexible filtering by Group or Term Set.