The primary keyword pnp people picker control in react for SPfx with example sets the scope: implement a production-grade People Picker in a SharePoint Framework (SPFx) web part using React, strict TypeScript, and Zod validation. Why this matters: avoid vague selections, respect tenant boundaries and theming, and ship a fast, accessible control that your security team can approve.
The Problem
Developers often wire up People Picker quickly, then face issues with invalid selections, poor performance in large tenants, theming mismatches, and missing API permissions. The goal is a robust People Picker that validates data, performs well, and aligns with SPFx and Microsoft 365 security constraints.
Prerequisites
- Node.js v20+
- SPFx v1.18+ (React and TypeScript template)
- @pnp/spfx-controls-react v3.23.0+ (PeoplePicker)
- TypeScript strict mode enabled ("strict": true)
- Zod v3.23.8+ for schema validation
- Tenant admin rights to approve Microsoft Graph permissions for the package
The Solution (Step-by-Step)
1) Install dependencies and pin versions
npm install @pnp/spfx-controls-react@3.23.0 zod@3.23.8
Recommendation: pin versions to prevent accidental breaking changes in builds.
2) Configure delegated permissions (least privilege)
In config/package-solution.json, request the minimum Graph scopes needed to resolve people:
{
"solution": {
"webApiPermissionRequests": [
{ "resource": "Microsoft Graph", "scope": "User.ReadBasic.All" },
{ "resource": "Microsoft Graph", "scope": "People.Read" }
]
}
}
After packaging and deploying, a tenant admin must approve these scopes. These are delegated permissions tied to the current user; no secrets or app-only access are required for the People Picker scenario.
3) Implement a strict, validated People Picker component
/* PeoplePickerField.tsx */
import * as React from "react";
import { useCallback, useMemo, useState } from "react";
import { WebPartContext } from "@microsoft/sp-webpart-base";
import { PeoplePicker, PrincipalType } from "@pnp/spfx-controls-react/lib/PeoplePicker";
import { z } from "zod";
// Define the shape we accept from People Picker selections
// The control returns IPrincipal-like objects; we validate subset we rely upon.
const PersonSchema = z.object({
id: z.union([z.string(), z.number()]), // Graph or SP ID can be number or string
secondaryText: z.string().nullable().optional(), // usually email or subtitle
text: z.string().min(1), // display name
});
const SelectedPeopleSchema = z.array(PersonSchema).max(5); // enforce cardinality
export type ValidPerson = z.infer<typeof PersonSchema>;
export interface PeoplePickerFieldProps {
context: WebPartContext; // SPFx context to ensure tenant and theme alignment
label?: string;
required?: boolean;
maxPeople?: number; // override default of 5
onChange: (people: ValidPerson[]) => void; // emits validated data only
}
// Memoized to avoid unnecessary re-renders in large forms
const PeoplePickerField: React.FC<PeoplePickerFieldProps> = ({
context,
label = "Assign to",
required = false,
maxPeople = 5,
onChange,
}) => {
// Internal state to show validation feedback
const [error, setError] = useState<string | null>(null);
// Enforce hard cap
const personSelectionLimit = useMemo(() => Math.min(Math.max(1, maxPeople), 25), [maxPeople]);
// Convert PeoplePicker selections through Zod
const handleChange = useCallback((items: unknown[]) => {
// PeoplePicker sends unknown shape; validate strictly before emitting
const parsed = SelectedPeopleSchema.safeParse(items);
if (!parsed.success) {
setError("Invalid selection. Please choose valid users only.");
onChange([]);
return;
}
// Optional business rule: ensure each user has an email-like secondaryText
const withEmail = parsed.data.filter(p => (p.secondaryText ?? "").includes("@"));
if (withEmail.length !== parsed.data.length) {
setError("Some selections are missing a valid email.");
onChange([]);
return;
}
setError(null);
onChange(parsed.data);
}, [onChange]);
return (
<div>
<label>{label}{required ? " *" : ""}</label>
{/**
* PeoplePicker respects SPFx theme through provided context.
* Use PrincipalType to limit search to users only, avoiding groups for clarity.
*/}
<PeoplePicker
context={context}
titleText={label}
personSelectionLimit={personSelectionLimit}
ensureUser={true} // resolves users to the site collection to avoid auth issues
showHiddenInUI={false}
principalTypes={[PrincipalType.User]}
resolveDelay={300} // debounce for performance in large tenants
onChange={handleChange}
required={required}
/>
{/** Live region for accessibility */}
<div aria-live="polite">{error ? error : ""}</div>
</div>
);
};
export default React.memo(PeoplePickerField);
Notes: resolveDelay reduces repeated queries while typing. principalTypes avoids unnecessary group matches unless you require them.
4) Use the field in a web part with validated submit
/* MyWebPartComponent.tsx */
import * as React from "react";
import { useCallback, useState } from "react";
import { WebPartContext } from "@microsoft/sp-webpart-base";
import PeoplePickerField, { ValidPerson } from "./PeoplePickerField";
interface MyWebPartProps { context: WebPartContext; }
const MyWebPartComponent: React.FC<MyWebPartProps> = ({ context }) => {
const [assignees, setAssignees] = useState<ValidPerson[]>([]);
const [submitStatus, setSubmitStatus] = useState<"idle" | "saving" | "success" | "error">("idle");
const handlePeopleChange = useCallback((people: ValidPerson[]) => setAssignees(people), []);
const handleSubmit = useCallback(async () => {
try {
setSubmitStatus("saving");
// Example: persist only the IDs or emails to a list/Graph to avoid storing PII redundantly
const payload = assignees.map(p => ({ id: String(p.id), email: p.secondaryText }));
// TODO: call a secure API (e.g., SPHttpClient to SharePoint list) using current user's context
await new Promise(r => setTimeout(r, 600)); // simulate network
setSubmitStatus("success");
} catch {
setSubmitStatus("error");
}
}, [assignees]);
return (
<div>
<h3>Create Task</h3>
<PeoplePickerField
context={context}
label="Assignees"
required={true}
maxPeople={3}
onChange={handlePeopleChange}
/>
<button onClick={handleSubmit} disabled={assignees.length === 0 || submitStatus === "saving"}>
Save
</button>
<div aria-live="polite">{submitStatus === "saving" ? "Saving..." : ""}</div>
<div aria-live="polite">{submitStatus === "success" ? "Saved" : ""}</div>
<div aria-live="polite">{submitStatus === "error" ? "Save failed" : ""}</div>
</div>
);
};
export default MyWebPartComponent;
5) Authentication in SPFx context
SPFx provides delegated authentication via the current user. For Microsoft Graph calls, use MSGraphClientFactory; for SharePoint calls, use SPHttpClient. You do not need to store tokens; SPFx handles tokens and consent. Avoid manual token acquisition unless implementing advanced scenarios.
6) Minimal test to validate the component contract
// PeoplePickerField.test.tsx
import React from "react";
import { render } from "@testing-library/react";
import PeoplePickerField from "./PeoplePickerField";
// Mock SPFx WebPartContext minimally for the control; provide shape your test runner needs
const mockContext = {} as unknown as any; // In real tests, provide a proper mock of the context APIs used by the control
test("renders label and enforces required", () => {
const { getByText } = render(
<PeoplePickerField context={mockContext} label="Assignees" required onChange={() => {}} />
);
expect(getByText(/Assignees/)).toBeTruthy();
});
Note: In integration tests, mount within an SPFx test harness or mock the PeoplePicker dependency. For unit tests, focus on validation logic paths invoked by onChange.
Best Practices & Security
- Least privilege permissions. Request only User.ReadBasic.All and People.Read for resolving users. Do not request write scopes unless necessary.
- Azure RBAC and Microsoft 365 roles. This scenario uses delegated permissions within Microsoft 365; no Azure subscription RBAC role is required. Users need a valid SharePoint license and access to the site. Tenant admin must approve Graph scopes. For directory-read scenarios beyond basics, Directory Readers role may be required by policy.
- PII hygiene. Persist only identifiers (e.g., user IDs or emails) rather than full profiles. Avoid logging personal data. Mask PII in telemetry.
- Performance. Use resolveDelay to debounce search. Limit personSelectionLimit to a realistic value (e.g., 3–5). Memoize the field (React.memo) and callbacks (useCallback) to reduce re-renders in complex forms.
- Accessibility. Provide aria-live regions for validation and submit status. Ensure color contrast via SPFx theming; the PeoplePicker uses SPFx theme tokens when context is provided.
- Theming. Always pass the SPFx context to ensure the control inherits the current site theme.
- Error resilience. Wrap parent forms with an error boundary to display a fallback UI if a child component throws.
- Versioning. Pin dependency versions in package.json to avoid unexpected changes. Regularly update to the latest stable to receive security fixes.
- No server-side tech references here. Entity Framework patterns such as AsNoTracking are not applicable in SPFx client-side code.
Example package.json pins
{
"dependencies": {
"@pnp/spfx-controls-react": "3.23.0",
"zod": "3.23.8"
}
}
Optional: Error boundary pattern
import React from "react";
class ErrorBoundary extends React.Component<{}, { hasError: boolean }> {
constructor(props: {}) {
super(props);
this.state = { hasError: false };
}
static getDerivedStateFromError() { return { hasError: true }; }
render() { return this.state.hasError ? <div>Something went wrong.</div> : this.props.children; }
}
export default ErrorBoundary;
Wrap your form: ErrorBoundary around MyWebPartComponent to ensure a graceful fallback.
Summary
- Implemented a strict, validated People Picker for SPFx with React, Zod, and tenant-aware theming via context.
- Applied least privilege delegated permissions with admin consent, clear performance tuning, and accessibility patterns.
- Hardened production readiness through validation-first design, memoization, testing hooks, and pinned dependencies.
