Using the PnP SPFx PeoplePicker Control in SharePoint Framework

The PeoplePicker control from the PnP SPFx React Controls library is one of the most useful components when building SharePoint Framework solutions that need user selection.

It simplifies searching and selecting users, groups, or security principals without manually calling SharePoint or Microsoft Graph APIs.

Official documentation:
PeoplePicker Official Docs

Why use PeoplePicker?

In many SPFx scenarios you need:

• Assign users to tasks
• Select approvers
• Build team selectors
• Create dynamic permission assignments
• Capture users in forms

Without this control, you would need:

• SharePoint REST API calls
• Microsoft Graph integration
• Debounce logic
• Search UI rendering
• Selection state management

The PnP control handles all of that.

The issue: Why was it not working?

Your original code had:

disabled={true}

This makes the control read-only.

That is why it appeared like this:

• Greyed out
• Not clickable
• Impossible to search

Also:

searchTextLimit={5}

means search only starts after typing 5 characters.

For testing, using 2 is better.

Final working example

PeoplePickerWp.tsx

import * as React from 'react';
import {
  IPeoplePickerContext,
  PeoplePicker,
  PrincipalType
} from "@pnp/spfx-controls-react/lib/PeoplePicker";
import { IPeoplePickerWpProps } from './IPeoplePickerWpProps';
const PeoplePickerWp: React.FC<IPeoplePickerWpProps> = ({ context }) => {
  const peoplePickerContext: IPeoplePickerContext = {
    absoluteUrl: context.pageContext.web.absoluteUrl,
    msGraphClientFactory: context.msGraphClientFactory,
    spHttpClient: context.spHttpClient
  };
  const _getPeoplePickerItems = (items: any[]) => {
    console.log("Selected items:", items);
  };
  return (
    <PeoplePicker
      context={peoplePickerContext}
      titleText="People Picker"
      personSelectionLimit={3}
      showtooltip={true}
      required={true}
      searchTextLimit={2}
      onChange={_getPeoplePickerItems}
      principalTypes={[PrincipalType.User]}
      resolveDelay={1000}
    />
  );
};
export default PeoplePickerWp;

Props explained

context

Required to allow the control to connect to SharePoint and Graph.

context={peoplePickerContext}

Contains:

• Site URL
• Graph client
• SharePoint HTTP client

titleText

Label displayed above the picker.

titleText="People Picker"

personSelectionLimit

Maximum selected users.

personSelectionLimit={3}

Example:

• 1 = single person
• 3 = up to three people

required

Makes the field mandatory.

required={true}

showtooltip

Shows user details on hover.

showtooltip={true}

searchTextLimit

Minimum typed characters before search begins.

searchTextLimit={2}

Good values:

• 2 → faster testing
• 3 → production recommendation
• 5 → stricter filtering

principalTypes

Defines what can be searched.

User only:

principalTypes={[PrincipalType.User]}

Other options:

PrincipalType.SharePointGroup
PrincipalType.SecurityGroup
PrincipalType.DistributionList

Multiple:

principalTypes={[
  PrincipalType.User,
  PrincipalType.SharePointGroup
]}

resolveDelay

Search delay in milliseconds.

resolveDelay={1000}

This reduces API calls while typing.

What the onChange returns

When a user is selected:

const _getPeoplePickerItems = (items: any[]) => {
  console.log(items);
};

Example object:

[
  {
    "id": "i:0#.f|membership|user@tenant.com",
    "text": "John Doe",
    "secondaryText": "user@tenant.com"
  }
]

Useful for:

• Saving into SharePoint lists
• Sending emails
• Permission assignment
• Workflow approvals

Common mistakes

1. Disabled picker

Wrong:

disabled={true}

Correct:

disabled={false}

or remove it.

2. Wrong context object

Wrong:

Passing full SPFx context directly.

Correct:

Build IPeoplePickerContext.

3. Search starts too late

Bad for testing:

searchTextLimit={5}

Better:

searchTextLimit={2}

4. Missing permissions

If Graph is required, ensure your package permissions are approved.

Especially when resolving users across the tenant.

Installation

Install the PnP library:

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

Run:

npm install

Start:

heft start

Real-world scenarios

PeoplePicker is excellent for:

References

PnP Controls:
PnP SPFx Controls Library

PeoplePicker:
PeoplePicker Documentation

SPFx official docs:
Microsoft SPFx Documentation

Microsoft Graph:
Microsoft Graph Documentation

The PeoplePicker is one of the core controls in the PnP SPFx ecosystem because it abstracts complex identity resolution into a single reusable component. For enterprise solutions, it is almost mandatory.