People picker component in Microsoft Graph Toolkit

You can use the mgt-people-picker web component to search for people, groups, or both. By default, the component searches for all people and users in the organization, but you can change the behavior to also search for groups, or only groups. You can also filter the search to a specific group. You can also allow the user to enter and select any email address.

Example

The following example shows the mgt-people-picker component. Start searching for a name to see the results render and use the code editor to see how properties change the behavior of the component.

Properties

By default, the mgt-people-picker component fetches people from the /me/people and /users endpoints. Use the following attributes to change this behavior.

The following example shows the show-max attribute.

<mgt-people-picker show-max="4"> </mgt-people-picker>

Selected people

The selected people section of the component renders each person chosen by the developer or user.

You can populate selected people data with the following options:

• Setting the selectedPeople property directly, as shown in the following example.

  // personObject is the User or Person object from Microsoft Graph
  document.querySelector("mgt-people-picker").selectedPeople.push(personObject);
  

• Using the selectUsersById() method, which accepts an array of Microsoft graph user IDs to find associated user details for selection.

  Note: If no user is found for an id, no data will be rendered for that id.

  // id = Microsoft graph User "id"
  document.querySelector("mgt-people-picker").selectUsersById(["id", "id"]);
  

• Using the selectGroupsById() method, which accepts an array of Microsoft graph group IDs to find the group(s) with associated users.

  // groupid = Microsoft graph group "id"
  document
    .querySelector("mgt-people-picker")
    .selectGroupsById(["groupid", "groupid"]);
  

CSS custom properties

The mgt-people-picker component defines the following CSS custom properties.

<mgt-people-picker class="people-picker"></mgt-people-picker>

.people-picker {
  --people-picker-selected-option-background-color: orange;
  --people-picker-selected-option-highlight-background-color: red;
  --people-picker-dropdown-background-color: blue;
  --people-picker-dropdown-result-background-color: yellow;
  --people-picker-dropdown-result-hover-background-color: gold;
  --people-picker-dropdown-result-focus-background-color: green;
  --people-picker-no-results-text-color: orange;
  --people-picker-input-background: gray;
  --people-picker-input-border-color: yellow;
  --people-picker-input-hover-background: green;
  --people-picker-input-hover-border-color: red;
  --people-picker-input-focus-background: purple;
  --people-picker-input-focus-border-color: orange;

  --people-picker-input-placeholder-focus-text-color: yellow;
  --people-picker-input-placeholder-hover-text-color: gold;
  --people-picker-input-placeholder-text-color: white;
  --people-picker-search-icon-color: yellow;
  --people-picker-remove-selected-close-icon-color: blue;

  /** Style for the avatar-size in the people-picker **/
  --people-picker-result-person-avatar-size: 50px;
  --people-picker-selected-person-avatar-size: 30px;

  /** You can also change the person tokens **/
  --person-line1-text-color: blue;
  --person-line2-text-color: red;
}

To learn more, see styling components.

Events

The following events are fired from the component.

For more information about handling events, see events.

Templates

mgt-people-picker supports several templates that you can use to replace certain parts of the component. To specify a template, include a <template> element inside a component and set the data-type to one of the following values.

The following examples show how to use the error template.

<mgt-people-picker>
  <template data-type="error">
    <p>Sorry, no people were found</p>
  </template>
</mgt-people-picker>

Microsoft Graph permissions

This component might make many queries depending on configuration and state. The following table splits the Microsoft Graph APIs and permissions that are required into three sections for simplicity. For each API called, the user must have at least one of the permissions listed.

Regardless of the user input state

When no user input is present

When a user has supplied a search term

Subcomponents

The mgt-people-picker component consists of one or more subcomponents that might require other permissions than the ones listed previously. For more information, see the documentation for each subcomponent: mgt-person.

Authentication

The control uses the global authentication provider described in the authentication documentation.

Cache

For more information about how to configure the cache, see Caching.

Extend for more control

For more complex scenarios or a truly custom UX, this component exposes several protected render* methods for override in component extensions.

Localization

The control exposes the following variables that can be localized. For details about localization, see Localizing components.