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:

Prerequisites

  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

Further Reading

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.