Person component in Microsoft Graph Toolkit

The person component is used to display a person or contact by using their photo, name, email address, or any other person details.

The person component also uses the mgt-person-card to display a flyout card with additional information about the user. For details, see the Person Card section.

Example

The following example displays a person using the mgt-person component. You can use the code editor to see how properties change the behavior of the component.

Setting the person details

You can use three properties to set the person details. Use only one of the following properties per instance:

• Set the user-id attribute or userId property to fetch the user from Microsoft Graph by using their ID.

• Set the person-query attribute or personQuery property to search Microsoft Graph for a given person. It chooses the first person available and fetches the person details. An email works best to ensure the right person is queried, but a name works as well.

• Set the person-presence attribute or personPresence property to add a presence badge to person avatar manually.

• Set the avatar-size attribute or avatarSize property to small or large to determine the size of avatar. This helps add the correct presence badge to the avatar. You need to choose the correct corresponding css custom properties shown below to further customize the avatar size. By default, the value is set to auto which will automatically decide how to render the presence based on the view property. We recommend using small if your avatar is smaller than 32px by 32px.

• Use the person-details attribute or personDetails property to manually set the person details, as shown in the following example.

  let personControl = document.getElementById('myPersonControl');
  personControl.personDetails = {
      displayName: 'Nikola Metulev',
      mail: '[email protected]',
      personImage: 'url'
  }
  

  If no image is provided, one is fetched (if available).

• By default, the person component only requests the standard Microsoft Graph user set of properties. In order to request additional properties, declare them as any part of the line(x)Property.

Properties

You can use several properties to customize the component.

CSS custom properties

The mgt-person component defines the following CSS custom properties.

<mgt-person class="person" person-query="me" view="fourlines" id="online" show-presence></mgt-person>

.person {
  --person-background-color: #616161;
  --person-background-border-radius: 30%;
  --person-avatar-size: 40px;
  --person-avatar-border: 3px solid yellow;
  --person-avatar-border-radius: 54%;
  --person-initials-text-color: white;
  --person-initials-background-color: blue;
  --person-line1-font-size: 32px;
  --person-line1-font-weight: 600;
  --person-line1-text-color: red;
  --person-line1-text-transform: capitalize;
  --person-line1-text-line-height: 20px;
  --person-line2-font-size: 28px;
  --person-line2-font-weight: 500;
  --person-line2-text-color: orange;
  --person-line2-text-transform: full-width;
  --person-line2-text-line-height: 16px;
  --person-line3-font-size: 24px;
  --person-line3-font-weight: 400;
  --person-line3-text-color: blue;
  --person-line3-text-transform: uppercase;
  --person-line3-text-line-height: 12px;
  --person-line4-font-size: 20px;
  --person-line4-font-weight: 300;
  --person-line4-text-color: green;
  --person-line4-text-transform: lowercase;
  --person-line4-text-line-height: 12px;
  --person-details-spacing: 30px;
}

To learn more, see styling components.

Events

The following events are fired from the component.

For more information about handling events, see events.

Templates

The mgt-person component supports several templates that allow you 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 example defines a template for the person component.

<!-- Retemplate the entire person component -->
<mgt-person>
  <template>
    <div data-if="personImage">
      <img src="{{personImage}}" />
    </div>
    <div data-else>
      {{person.displayName}}
    </div>
  </template>
</mgt-person>

<!-- Retemplate the line properties -->
<mgt-person view="threeLines">
  <template data-type="line1">
    <div>
      Hello, my name is: {{person.displayName}}
    </div>
  </template>
  <template data-type="line2">
    <div>
      Super cool
    </div>
  </template>
  <template data-type="line3">
    <div>
      Loves MGT
    </div>
  </template>
</mgt-person>

<mgt-person view="fourLines">
  <template data-type="line1">
    <div>
      Hello, my name is: {{person.displayName}}
    </div>
  </template>
  <template data-type="line2">
    <div>
      Musician
    </div>
  </template>
  <template data-type="line3">
    <div>
      Calif records
    </div>
  </template>
  <template data-type="line4">
    <div>
      {{person.mail}}
    </div>
  </template>
</mgt-person>

<!-- Person-card template -->
<mgt-person person-query="me" view="twolines" person-card="hover">
	<template data-type="person-card">
		My custom person card experience
	</template>
</mgt-person>

Person card

The mgt-person component can show an mgt-person-card on either hover or click.

Add the control to the HTML page

<mgt-person person-query="me" person-card="hover"></mgt-person>

For more information about templating, styling, and attributes, see Person Card component.

Global component configuration

The MgtPerson class exposes a static config object that configures all person components in the application.

The following example shows how to use the config object.

import { MgtPerson } from '@microsoft/mgt-components';

MgtPerson.config.useContactApis = false;

The following properties are available on the config object.

Microsoft Graph permissions

This control uses the following Microsoft Graph APIs and permissions. For each API called, the user must have at least one of the permissions listed. Some configurations can result in multiple calls to Microsoft Graph. When these calls can use different permissions, each API and permission set is in a separate row.

Subcomponents

The mgt-person 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-card.

Authentication

The control uses the global authentication provider described in the authentication documentation to fetch the required data.

Cache

See Caching for more details on how to configure the cache.

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 how to set up localization, see Localizing components.