Person component in Microsoft Graph Toolkit

Caution

The Microsoft Graph Toolkit is deprecated. The retirement period begins September 1, 2025, with full retirement planned for August 28, 2026. Developers should migrate to using the Microsoft Graph SDKs or other supported Microsoft Graph tools for building web experiences. For more information, see the deprecation announcement.

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.

HTML
React

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 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: 'nikola@contoso.com',
    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.

Attribute	Property	Description
user-id	userId	Set to a user ID to fetch that user's details and image from Microsoft Graph.
person-query	personQuery	Set to a name or email of a person to search for a person in Microsoft Graph and fetch the first person's details and image.
person-details	personDetails	Set to an object representing a person. Works with objects from the people, users, contacts, or group, resources.
fallback-details	fallbackDetails	Set to an object representing a person when no user/person/contact is found in Microsoft Graph.
person-image	personImage	Set the image to show for the person.
person-presence	personPresence	Set the presence for the person.
fetch-image	fetchImage	Set flag to fetch `personImage` automatically from Microsoft Graph based on the `personDetails` object provided by the user.
disable-image-fetch	disableImageFetch	Set flag to disable fetching of person image. It can be used to avoid unnecessary fetching from Microsoft Graph when specifying `personImage` property.
avatar-type	avatarType	Set to `initials` or `photo` to render either display state - default is photo.
avatar-size	avatarSize	Set the avatar size to `small`, `large`, or `auto`, helping also determine the correct size for the presence badge. The default value is `auto`. If the `view` attribute is set to `threelines` or `fourlines`, `avatar-size` is automatically treated as `large`, regardless of its actual value.
vertical-layout	verticalLayout	Set the component layout to vertical.
view	view	Set to control how the person is rendered. Default is `image`. `image` - show only avatar `oneline` - show avatar and first line (`displayName` by default) `twolines` - show avatar and two lines of text (`displayName` and `jobTitle` by default) `threelines` - show avatar and three lines of text (`displayName`, `jobTitle` and `department` by default) `fourlines` - show avatar and four lines of text (`displayName`, `jobTitle`, `department` and `email` by default) In `vertical-layout`, view changes. `twolines` - show avatar and two lines of text (`displayName` and `email` by default) `threelines` - show avatar and three lines of text (`displayName` , `email` and `department` by default)
line1-property	line1Property	Sets the property of the personDetails to use for the first line of text. Default is `displayName`.
line2-property	line2Property	Sets the property of the personDetails to use for the second line of text. Default is `jobTitle`.
line3-property	line3Property	Sets the property of the personDetails to use for the third line of text. Default is `department`.
line4-property	line4Property	Sets the property of the personDetails to use for the fourth line of text. Default is `email`.
show-presence	showPresence	Set flag to display person presence - default is `false`.
usage	usage	Specify where the component is being used in order to add customized personalization for it. Currently only supports `people` as used in the people component.
person-card	personCardInteraction	Sets the behavior to show the person card on the rendered person component. The allowed values are `none`, `hover` or `click`. Default is `none`.

CSS custom properties

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

.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.

Event	When is it emitted	Custom data	Cancelable	Bubbles	Works with custom template
`line1clicked`	Fired when line1 is clicked	The `person` object which can be a Microsoft Graph user, person, or contact with an additional `personImage` property that contains the URL of the user's photo.	No	No	Yes, unless you override the default template.
`line2clicked`	Fired when line2 is clicked	The `person` object which can be a Microsoft Graph user, person, or contact with an additional `personImage` property that contains the URL of the user's photo.	No	No	Yes, unless you override the default template.
`line3clicked`	Fired when line3 is clicked	The `person` object, which can be a Microsoft Graph user, person, or contact with an additional `personImage` property that contains the URL of the user's photo.	No	No	Yes, unless you override the default template.
`line4clicked`	Fired when line4 is clicked	The `person` object, which can be a Microsoft Graph user, person, or contact with an additional `personImage` property that contains the URL of the user's photo.	No	No	Yes, unless you override the default template.

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

Data type	Data context	Description
loading	none	The template to render while the component is in a loading 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 `personPresence`: The presence details object for person.	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.
line1	person: The person details object	The template for the first line of person metadata.
line2	person: The person details object	The template for the second line of person metadata.
line3	person: The person details object	The template for the third line of person metadata.
line4	person: The person details object	The template for the fourth line of person metadata.

Configuration	Permission	API
`personDetails` set without image, `fetchImage` set to `true`, `avatarType` set to `photo`, retrieved person is a contact and `useContactApis` set to `true`	Contacts.Read, Contacts.ReadWrite	/me/contacts/*
`personDetails` set without image, `fetchImage` set to `true`, `avatarType` set to `photo` and person isn't a contact or `useContactApis` is set to `false`	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/users/{id}/photo/$value
`personDetails` set without image, `fetchImage` set to `true`, `avatarType` set to `photo` and user specified via email	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users?$search=
`personDetails` set without image, `fetchImage` set to `true`, `avatarType` set to `photo` and user specified via email	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/users/{id}/photo/$value
`personDetails` set without image, `fetchImage` set to `true`, `avatarType` set to `photo` and contact specified via email and `useContactApis` set to true	Contacts.Read, Contacts.ReadWrite	/me/contacts/*
`personDetails` set without image to a group, `fetchImage` set to `true`, `avatarType` set to `photo`	Group.Read.All, Group.ReadWrite.All'	/groups/${groupId}/photo/$value
`userId` set	User.ReadBasic.All	/users/{id}
`userId` set or `personQuery` set to `me` and `avatarType` set to `photo` and `disableImageFetch` is `false`	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/users/{id}
`userId` set or `personQuery` set to `me` and `avatarType` set to `photo` and `disableImageFetch` is `false`	User.ReadBasic.All, User.Read.All, User.ReadWrite.All	users/${userId}/photo/*
`userId` set to `me` and `avatarType` set to `photo` and `disableImageFetch` is `false`	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/me
`userId` set to `me` and `avatarType` set to `photo` and `disableImageFetch` is `false`	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All	/me/photo/$value
`personQuery` set to `me` and `avatarType` set to something else than `photo`	User.Read, User.ReadWrite	/me
`personQuery` set to a value other than `me` and `avatarType` set to something else than `photo`	People.Read, People.Read.All	/me/people
`personQuery` set to a value other than `me` and `avatarType` set to something else than `photo` and `/me/people` returned no data matching the supplied `personQuery`	User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All	/user?$search=
`personQuery` set to a value other than `me` and `useContactApis` set to `false`	People.Read, User.ReadBasic.All	/me/people/?$search=, /users?$search=
`showPresence` set to `true` and `personQuery` set to `me`	Presence.Read	/me/presence
`showPresence` set to `true` and `personQuery` set to a value other than `me`	Presence.Read.All	/users/{id}/presence
`personCardInteraction` set to a value other than `PersonCardInteraction.none`	See person card permissions	See person card API calls

Object store	Cached data	Remarks
`photos`	Person's photo	Used when `avatarType` is set to `photo` and `fetchImage` is set to `true`.
`presence`	Person's presence	Used when `showPresence` is set to `true`.
`users`	Person's user information.

Method	Description
renderLoading	Renders the loading state.
renderNoData	Renders when no image or person data is available.
renderAvatar	Renders the avatar.
renderDetails	Renders the person details part.

String name	Default value
photoFor	`Photo for`
emailAddress	`Email address`

Person card

Add the control to the HTML page

Global component configuration

Microsoft Graph permissions

Subcomponents

Authentication

Cache

Extend for more control

Localization

Feedback

Additional resources