Web Parts
People Listing
Display people from People Search API or a curated SharePoint list with card or list layouts.
PeopleFeature Parity: 100%
Get People Listing Working in 3 Steps
15-30 minutes
Prerequisites
- Bonzai 2 package installed on your site
- For List mode: a SharePoint list with a Person/Group column (roster) or text fields (external contacts)
1
Add the web part
Edit your page and add "Bonzai People Listing" from the Bonzai category.
2
Choose data source
Select "People Search (Organization Directory)" for Azure AD users or "SharePoint List" for curated people. For List mode, also pick a list schema (Person/Group roster or External contacts).
3
Configure display and filters
Pick Cards or List/Table layout, set items per page, toggle field visibility, and optionally enable the A–Z filter or refiners.
Two data source modes, two list schemas
People Listing supports two data sources: People Search (Azure AD users via SharePoint Search) or SharePoint List. In List mode you pick a schema: Person/Group roster(uses a Person column and pulls directory profile data) or External contacts(maps plain text/URL fields for people not in Azure AD).
Data Source Modes
- People Search: Uses the SharePoint Search API with the People result source to display users from Azure AD. Supports free-text search, optional A–Z filter, Department/Job Title/Location refiners, and an admin-defined fixed KQL filter.
- SharePoint List — Person/Group roster: Pulls items from a list with a Person/Group column. Profile details (job title, department, office, phone) are read directly from the chosen user.
- SharePoint List — External contacts: Pulls items from a list of plain-text rows and maps your columns (Name, Email, Job Title, Department, Location, Phone, Profile URL, Photo URL) onto the person card. Ideal for people not in Azure AD.
Advanced filtering, built-in
Enable
showAZFilter for a quick alphabetical browse, showRefiners for Department / Job Title / Location dropdowns, and fixedFilterQuery to pin every query to a specific slice of the directory (e.g. Department:"IT").When to Use This Web Part
Use this when you need to...
- Display a curated team member list
- Show specific people (leadership, project team)
- Create an "Our Team" section
- Browse an organization directory with A–Z and refiners
- Display external contacts not in Azure AD
Best page locations
- About Us page — leadership team
- Department pages — team members
- Project pages — project team
- Homepage — team spotlight widget
- Partner / vendor directories (External contacts schema)
Consider alternatives when...
- • Cross-site employee search with full-tenant indexing — consider a dedicated search centre
Related web parts:
Spotlight Rollup — featured employee storiesContent Cards — mixed news/people tile layouts
Common Configurations
Organization Team Grid
Card layout from People Search
Best for: People page
Configuration
| title | Our Team |
| dataSource | People Search |
| displayAs | Cards |
| itemsPerPage | 12 |
| showPhoto | On |
| showJobTitle | On |
| showDepartment | On |
A–Z Directory with Refiners
Browse the whole org by letter, then filter
Best for: Directory page
Configuration
| title | People Directory |
| dataSource | People Search |
| showAZFilter | On |
| alphabeticalFilterField | PreferredName |
| showRefiners | On |
| itemsPerPage | 18 |
Leadership Team (curated)
Person/Group roster with fixed order
Best for: About Us page
Configuration
| title | Leadership |
| dataSource | SharePoint List |
| listSchema | Person/Group roster |
| listName | Leadership Team |
| personColumn | Person |
| listSortBy | Custom field |
| listSortField | SortOrder |
| showPaging | Off |
Project Team List
Compact list/table view of team
Best for: Project page
Configuration
| title | Project Team |
| dataSource | SharePoint List |
| listSchema | Person/Group roster |
| listName | Project Teams |
| personColumn | Member |
| displayAs | List |
| showTableHeaders | On |
Department Members
People Search pinned to one department
Best for: Department page
Configuration
| title | HR Team |
| dataSource | People Search |
| fixedFilterQuery | Department:"Human Resources" |
| displayAs | Cards |
| showEmail | On |
| showPhone | On |
External Contacts
Partners / vendors not in Azure AD
Best for: Partner directory
Configuration
| title | Partners |
| dataSource | SharePoint List |
| listSchema | External contacts |
| listName | Partners |
| externalNameField | Title |
| externalEmailField | |
| externalJobTitleField | JobTitle |
| externalPhotoUrlField | PhotoUrl |
Best Practices
Use People Search for live directory data
People Search mode automatically pulls photos, titles, and departments from Azure AD / Delve profiles — no list maintenance needed.
Use List mode for curated ordering
List mode gives you full control over who appears and in what order. Use the List Sortinggroup to sort by person name or by a custom field like
SortOrder.Pin a query with Fixed Filter (KQL)
In People Search mode,
fixedFilterQuery is appended to every query, so you can create a department- or location-specific rollup that still benefits from live search. Example:Department:"IT" or BaseOfficeLocation:"Seattle".External contacts = full field mapping
When
listSchema is External contacts, every person field (name, email, job title, department, location, phone, profile URL, photo URL) is mapped from a column you choose. Only the Name field is required; leave others blank to hide.Reference
List Schema A — Person/Group Roster
Choose this schema when everyone you want to display is a directory user (Azure AD / Microsoft 365). You only need one required column: a Person or Group column. All profile fields (email, job title, department, office, phone) are read from the selected user, not from separate list columns.
- Create a SharePoint list for the roster.
- Add a Person or Group column (e.g. "Person" or "Member"). Multi-value is supported.
- In the web part, set
listSchemato Person/Group roster (directory identities) and pick that column in the Person Column dropdown (auto-populated from the selected list). - Optional: add columns for sort order or extra metadata (see
listSortFieldandadditionalColumns).
| Column | Type | Required | Description |
|---|---|---|---|
| Title | Single line of text | Built-in | Default SharePoint Title column; not displayed. |
| (Person column — named by you) | Person or Group | Yes | Selected via the personColumn dropdown. Provides name, email, job title, department, office, phone. |
| SortOrder (optional) | Number | No | Any numeric/text field you want to sort by — pair with listSortBy = field and listSortField. |
| Promoted (optional) | Yes/No | No | When present and showPromotedItems is on, only items with Promoted = true are returned. |
| (Additional) | Various | No | Extra columns shown as extra List-view columns via additionalColumns (format Title:InternalName;Title2:InternalName2). |
List Schema B — External Contacts
Choose this schema for people not in your directory (partners, vendors, advisors). You map plain-text / hyperlink columns on your list onto the person card fields. Only the Namefield mapping is required; any other mapping left blank simply hides that field.
- Create a SharePoint list with your own columns (any names you like).
- In the web part, set
listSchemato External contacts (text fields). - Map each person field to an internal column name via the dropdowns — see defaults below.
| Person field | Web part property | Default mapping | Required |
|---|---|---|---|
| Name | externalNameField | Title | Yes |
externalEmailField | Email | No | |
| Job Title | externalJobTitleField | JobTitle | No |
| Department | externalDepartmentField | Department | No |
| Location | externalLocationField | Office | No |
| Phone | externalPhoneField | Phone | No |
| Profile URL | externalProfileUrlField | (empty) | No |
| Photo URL | externalPhotoUrlField | (empty) | No |
Defaults are suggestions only
The defaults above are the values saved in the manifest so the dropdowns aren't blank on first use — they still have to exist as actual columns on your list. Create any columns you need, then map them in the property pane.
Property Pane Configuration
Title Settings
| Property | Type | Default | Description |
|---|---|---|---|
title | Text | People | Web part title. Leave blank to hide the header entirely. |
titleUrl | Text | (empty) | Optional URL to make the title clickable. |
titleIconOption | Dropdown | custom | Title icon mode: custom (Select Icon) or none. |
titleIconName | Text | People | Fluent UI icon name (shown when titleIconOption = custom). |
titleIconUrl | Text | (empty) | Custom icon URL (overrides titleIconName). |
description | Text (multiline) | (empty) | Optional description below the title. |
showMoreText | Text | (empty) | Text for the footer link shown below the list. |
showMoreUrl | Text | (empty) | URL for the footer link. Footer only renders when both text and URL are set. |
chromeType | Dropdown | titleAndBorder | Chrome: none, titleOnly, borderOnly, or titleAndBorder. |
Data Source Selection
| Property | Type | Default | Description |
|---|---|---|---|
dataSource | Dropdown | peopleSearch | peopleSearch (People Search — Organization Directory) or list (SharePoint List). |
People Search Settings (when dataSource = peopleSearch)
| Property | Type | Default | Description |
|---|---|---|---|
resultSource | Text | Local People Results | SharePoint search result source name or GUID. The web part maps Local People Results / People to the standard people source ID, or accepts a tenant-specific GUID directly. |
searchPlaceholder | Text | Search people... | Placeholder text for the search box. |
showAZFilter | Toggle | Off | Shows an A–Z letter bar above the results for quick alphabetical browsing. |
alphabeticalFilterField | Text | PreferredName | Managed property used for A–Z filtering. Disabled until showAZFilter is on. Falls back to PreferredName if the custom field fails. |
fixedFilterQuery | Text (multiline) | (empty) | Admin-defined KQL appended to every query (e.g. Department:"IT"). Use this to pin the web part to a slice of the directory. |
Search behaviour
Typing in the search box runs (debounced) a KQL OR across
PreferredName,WorkEmail, JobTitle, and Department. The A–Z, refiners, and fixed filter are combined with the free-text query using AND, so they always narrow results.List Settings (when dataSource = list)
| Property | Type | Default | Description |
|---|---|---|---|
siteUrl | Text | (empty) | Site URL where the list lives. Leave empty to use the current site. |
listName | List Picker | (none) | SharePoint list picker (returns { id, title, url } under the hood; strings are also supported for back-compat). |
listSchema | Dropdown | person | person (Person/Group roster) or external (External contacts). |
personColumn | Dropdown | (empty) | Shown when listSchema = person. Auto-populated with the list's Person/Group columns (type User or UserMulti). Disabled until a list is selected. |
additionalColumns | Text (multiline) | (empty) | Extra columns to add to the List/Table view. Format: Title:InternalName;Title2:InternalName2 (or just InternalName;InternalName2). |
showPromotedItems | Toggle | Off | When on, filters to items where a Promoted Yes/No column equals true. Requires the column to exist on the list. |
External Schema Field Mapping (when listSchema = external)
Each property below is a dropdown that maps a person field onto a column on the selected list. Values shown here are the manifest defaults — they are just starting suggestions and still have to exist as real columns.
| Property | Type | Default | Description |
|---|---|---|---|
externalNameField | Dropdown | Title | Required. Column used as the display name. |
externalEmailField | Dropdown | Email | Column used for email (and the mail action icon). |
externalJobTitleField | Dropdown | JobTitle | Column used for job title. |
externalDepartmentField | Dropdown | Department | Column used for department. |
externalLocationField | Dropdown | Office | Column used for location / office. |
externalPhoneField | Dropdown | Phone | Column used for phone (and the tel action icon). |
externalProfileUrlField | Dropdown | (empty) | Optional column with a URL used as the card/name link. |
externalPhotoUrlField | Dropdown | (empty) | Optional column with an image URL used as the profile photo. |
List Sorting
| Property | Type | Default | Description |
|---|---|---|---|
listSortBy | Dropdown | personName | personName (sort by the person's display name), field (sort by a column you pick), or default (SharePoint default order). |
listSortField | Text | SortOrder | Internal name of the column to sort by. Only applied when listSortBy = field. |
listSortDirection | Dropdown | asc | asc or desc. Disabled when listSortBy = default. |
viewName is deprecated
Earlier builds exposed a View Picker (
viewName). It is no longer surfaced in the property pane and list queries do not apply the view. The value is retained on existing saved configs for backward compatibility only; use List Sorting andShow promoted items only instead.Field Visibility
| Property | Type | Default | Description |
|---|---|---|---|
showPhoto | Toggle | On | Show profile photo on cards and in the Name column of the List/Table view. |
showJobTitle | Toggle | On | Show job title. |
showDepartment | Toggle | On | Show department. |
showLocation | Toggle | On | Show location / office. |
showEmail | Toggle | On | Show email (mail icon on cards, Email column in List view). |
showPhone | Toggle | On | Show phone (phone icon on cards, Phone column in List view). |
Display Options
| Property | Type | Default | Description |
|---|---|---|---|
displayAs | Dropdown | cards | cards (grid of person cards) or list (DetailsList / table). |
itemsPerPage | Slider | 12 | People per page. Range 6–30, step 3. |
showPaging | Toggle | On | Show the pagination bar (only renders when there is more than one page). |
showSearch | Toggle | On | Show the search box above the results. |
showRefiners | Toggle | Off | Show Department / Job Title / Location dropdown refiners. Options are built from the currently visible people. |
showTableHeaders | Toggle | On | Show column headers in the List/Table view. |
fixedHeight | Slider | 0 | Fixed container height in pixels (0 = auto). Range 0–800, step 50. Overflow scrolls inside the web part. |
Features Checklist
- ✅ Two data source modes (People Search, SharePoint List)
- ✅ Two list schemas (Person/Group roster, External contacts)
- ✅ Cards and List/Table display layouts
- ✅ Configurable field visibility (photo, job title, department, location, email, phone)
- ✅ Debounced free-text search across name / email / job title / department
- ✅ A–Z alphabetical filter (configurable managed property in People Search mode)
- ✅ Refiners: Department / Job Title / Location dropdowns
- ✅ Fixed KQL filter (admin-defined, People Search mode)
- ✅ List sorting by person name or custom field, ascending/descending
- ✅ Promoted-items-only toggle (List mode)
- ✅ Pagination with total count
- ✅ Profile photos (Delve in directory modes; mapped column in External contacts)
- ✅ Additional columns injected into the List/Table view
- ✅ Fixed container height with internal scroll