Skip to content

People Picker

This control renders a People picker field which can be used to select one or more users from a SharePoint group or site. The control can be configured as mandatory. It will show a custom error message if field is empty.


You can also check out People Picker component in the Microsoft Graph Toolkit.

Empty People Picker control with error message and tooltip

People Picker

Selecting People

Selecting People

Selected people

Selected people

How to use this control in your solutions

  • Check that you installed the @pnp/spfx-controls-react dependency. Check out the getting started page for more information about installing the dependency.
  • Import the following modules to your component:
import { IPeoplePickerContext, PeoplePicker, PrincipalType } from "@pnp/spfx-controls-react/lib/PeoplePicker";
  • Use the PeoplePicker control in your code as follows:
const peoplePickerContext: IPeoplePickerContext = {
    absoluteUrl: this.props.context.pageContext.web.absoluteUrl,
    msGraphClientFactory: this.props.context.msGraphClientFactory,
    spHttpClient: this.props.context.spHttpClient

    titleText="People Picker"
    groupName={"Team Site Owners"} // Leave this blank in case you want to filter from all users
    resolveDelay={1000} />
  • With the onChange property you can get the selected People in the PeoplePicker :
private _getPeoplePickerItems(items: any[]) {
  console.log('Items:', items);


The People picker control can be configured with the following properties:

Property Type Required Description Default
context IPeoplePickerContext yes Context of the component, based on the SPFx context (BaseComponentContext).
titleText string no Text to be displayed on the control
groupName string no Group from which users are fetched. Leave it blank if need to filter all users. When both groupName and groupId specified groupName takes precedence. none
groupId number | string | (string|number)[] no Group from which users are fetched. Leave it blank if need to filter all users. When both groupId and groupName specified groupName takes precedence. If string is specified, Microsoft 365 Group is used. If array is used, fetch results from multiple groups none
personSelectionLimit number no Defines the limit of people that can be selected in the control 1
required boolean no Set if the control is required or not false
disabled boolean no Set if the control is disabled or not false
errorMessage string no Static error message displayed below the picker. Use onGetErrorMessage to dynamically change the error message displayed (if any) based on the current value. errorMessage and onGetErrorMessage are mutually exclusive (errorMessage takes precedence).
onGetErrorMessage (items: IPersonaProps[]) => string | Promise<string> no The method is used to get the validation error message and determine whether the picker value is valid or not. Mutually exclusive with the static string errorMessage (it will take precedence over this).
When it returns string:
  • If valid, it returns empty string.
  • If invalid, it returns the error message string to be shown below the picker.

When it returns Promise<string>:
  • The resolved value is display as error message.
  • The rejected, the value is thrown away.
errorMessageClassName string no applies custom styling to the error message section
showtooltip boolean no Defines if need a tooltip or not false
tooltipMessage string no Specify the tooltip message to display
tooltipDirectional DirectionalHint no Direction where the tooltip would be shown
onChange (items: IPersonaProps[]) => void no Get the selected users in the control.
peoplePickerWPclassName string no applies custom styling to the people picker element
peoplePickerCntrlclassName string no applies custom styling to the people picker control only
defaultSelectedUsers string[] no Default selected user emails or login names, optionally append /title with forward slash. If user is not found then only optional title will be shown. If you do not have email or login name of inactive users just pass /title alone prefixed with slash.
webAbsoluteUrl string no Specify the site URL on which you want to perform the user query call. If not provided, the people picker will perform a tenant wide people/group search. When provided it will search users/groups on the provided site.
principalTypes PrincipalType[] no Define which type of data you want to retrieve: User, SharePoint groups, Security groups. Multiple are possible.
ensureUser boolean no When ensure user property is true, it will return the local user ID on the current site when doing a tenant wide search. false
allowUnvalidated boolean no When true, allow email addresses that have not been validated to be entered, effectively allowing any user. false
suggestionsLimit number no Maximum number of suggestions to show in the full suggestion list. 5
resolveDelay number no Add delay to resolve and search users 200
placeholder string no Short text hint to display in empty picker
styles Partial no Styles to apply on control
searchTextLimit number no Specifies the minimum character count needed to begin retrieving search results. 2

Enum PrincipalType

The PrincipalType enum can be used to specify the types of information you want to query: User, Security groups, and/or SharePoint groups.

Name Value
User 1
DistributionList 2
SecurityGroup 4
SharePointGroup 8

Interface IPeoplePickerContext

Provides mandatory properties to search users on the tenant

Value Type Description
absoluteUrl string Current SPWeb absolute URL.
msGraphClientFactory MSGraphClientFactory Instance of MSGraphClientFactory used for querying Microsoft Graph REST API.
spHttpClient SPHttpClient Instance of SPHttpClient used for querying SharePoint REST API.

MSGraph Permissions required

This control requires at least one the following scopes if groupId is of type string:

  • GroupMember.Read.All + User.ReadBasic.All
  • Directory.Read.All