Person component in the Microsoft Graph Toolkit

The person component is used to display a person or contact by using their photo, name, and/or email address.

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.

Open this example in mgt.dev

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 will choose the first person available and fetch the person details. An email works best to ensure the right person is queried, but a name works as well.

  • Set 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',
        email: 'nikola@contoso.com',
        image: 'url'
    }
    

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

Properties

You can use several properties to customize the component.

Attribute Property Description
show-name showName Set flag to display person display name - default is false.
show-email showEmail Set flag to display person email - default is false.

CSS custom properties

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

mgt-person {
  --avatar-size-s: 24px;
  --avatar-size: 48px; // avatar size when both name and email are shown
  --avatar-font-size--s: 16px;
  --avatar-font-size: 32px; // font-size when both name and email are shown
  --avatar-border: 0;
  --initials-color: white;
  --initials-background-color: magenta;
  --font-size: 12px;
  --font-weight: 500;
  --color: black;
  --email-font-size: 12px;
  --email-color: black;
}

To learn more, see styling components.

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 value to one of the following:

Data type Data context Description
loading none The template to render while the component is in a laoding state.
no-data none The template to render when no person image or data is available.
default person: The person details object
personImage: The URL of the image
The default template replaces the entire component with your own.
person-card person: The person details object
personImage: The URL of the image
The template to update the mgt-person-card displayed on hover or click.

The following example defines a template for the person component.

<mgt-person>
  <template>
    <div data-if="person.image">
      <img src="{{person.image}}" />
    </div>
    <div data-else>
      {{person.displayName}}
    </div>
  </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>
Attribute Property Description
person-card personCardInteraction An enumeration to determine user action necessary to activate flyout panel - hover or click. Default value is none

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

Microsoft Graph permissions

This control uses the following Microsoft Graph APIs and permissions.

Resource Permission
/me User.Read
/me/photo/$value User.Read
/me/people/?$search= People.Read
/me/contacts/* Contacts.Read
/users/{id}/photo/$value User.ReadBasic.All

Note: to access the */photo/$value resources for personal Microsoft accounts, use the Microsoft Graph beta endpoint.

Authentication

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

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.

Method Description
renderLoading Renders the loading state.
renderImage Renders the image part.
renderNoData Renders when no image or person data is available.
renderDetails Renders the person details part.
renderEmail Renders the email sub-part of the person details.
renderName Renders the name sub-part of the person details.