Implementing PnP People Picker in SharePoint Framework (SPFx)

In SharePoint Framework (SPFx) development, selecting users and groups is a common requirement for forms, dashboards, or workflow initiation. Thankfully, the PnP PeoplePicker control makes this seamless by offering a rich, customizable UI for selecting SharePoint users, AD groups, and more.

In this article, we’ll explore how to set up and use the PnP PeoplePicker in an SPFx project—from installation to real-world usage with a SharePoint list.

What is PnP PeoplePicker?

The PeoplePicker is part of the @pnp/spfx-controls-react package. It provides:

• Support for single/multiple selection
• Integration with SharePoint users, groups, and AD entities
• Easy integration with SPFx and Microsoft Graph
• Fully styled and responsive out of the box

Prerequisites

• SharePoint Online tenant with SPFx enabled
• Node.js (v16 recommended)
• Yeoman SPFx generator
• Code editor (e.g., VS Code)

1. Install the PnP SPFx Controls
   
   First, install the control package in your SPFx project

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

   This package contains many useful controls, including PeoplePicker.
    
2. Add PeoplePicker to Your Component
   
   Import the control and necessary enums:

   import {
     PeoplePicker,
     PrincipalType,
     IPeoplePickerContext,
   } from "@pnp/spfx-controls-react/lib/PeoplePicker";

   PrincipalType determines what types of users/entities can be selected (e.g., User, SharePointGroup, SecurityGroup).
    
3. Prepare the Required Context
   
   The PeoplePicker needs context to access SharePoint and Graph

   const peoplePickerContext: IPeoplePickerContext = {
     absoluteUrl: props.context.pageContext.web.absoluteUrl,
     msGraphClientFactory: props.context.msGraphClientFactory,
     spHttpClient: props.context.spHttpClient,
   };

   Pass the context via props to component function and create and people picker context and use it it in component.
    
4. Add the Control to Your JSX
   
   Here’s a minimal implementation for multiple user selection

   <PeoplePicker
     context={peoplePickerContext}
     titleText="Assign To"
     personSelectionLimit={5}
     showtooltip={true}
     required={true}
     disabled={false}
     onChange={handleUserChange}
     principalTypes={[
       PrincipalType.User,
       PrincipalType.SecurityGroup,
       PrincipalType.SharePointGroup,
     ]}
     resolveDelay={500}
   />

   Common Props:

   Prop	Description
   context	Required SPFx + Graph context
   titleText	Label for the picker
   personSelectionLimit	Number of users/groups that can be selected
   onChange	Callback with selected users
   principalTypes	Limits what entities are selectable

5. Handling the Selected Users
   
   The onChange callback gives you an array of selected users:

   const handleUserChange = (items: any[]) => {
     console.log("Selected Users:", items);
     setUsers(items); // save to local state or Formik
   };

   Sample Item Format

   {
     id: "i:0#.f|membership|[email protected]",
     loginName: "i:0#.f|membership|[email protected]",
     fullName: "User Name",
     email: "[email protected]"
   }

   Store this loginName or email for saving to SharePoint or sending via Graph API.
    
6. Saving to SharePoint List
   
   When saving to a SharePoint Person or Group column, you’ll need to ensure the user exists and get their SharePoint user ID

   const peopleField = values.users.map((user: any) => ({
     Key: user.loginName,
   }));
   
   await sp.web.lists.getByTitle("YourList").items.add({
     Title: "Item Title",
     PeopleField: { results: peopleField },
   });

7. Default Values and Edit Mode
   
   To set default selected users

   <PeoplePicker
     context={props.context}
     defaultSelectedUsers={["[email protected]"]}
     selectedItems={handlePeoplePickerChange}
     principalTypes={[PrincipalType.User]}
   />

   Note: Use email or login name in defaultSelectedUsers.

Tips for Production

• Validation: Ensure that required user fields are validated either through Formik or custom logic.
• Performance: Set resolveDelay to avoid rapid API calls.
• Security: Validate user input server-side when storing to SharePoint.

Further Reading

• PnP React Controls Documentation

Conclusion

The PnP People Picker is an excellent control for integrating user selection in SPFx applications. It is simple to use, well-documented, and offers flexibility for real-world requirements. With minimal configuration, you can create powerful forms that integrate deeply with SharePoint and Microsoft 365.