Person-Card component in Microsoft Graph Toolkit
A Person-Card component is a responsive component to display more information related to a person. It's used as a flyout on the mgt-person component.
For more information about the mgt-person component, see mgt-person.
Example using mgt-person
The following example shows the use of the mgt-person-card component with a mgt-person component. Hover or click on the person to see the Person Card.
Example using mgt-person-card as a standalone component
The following example shows the use of the mgt-person-card component. Use the code editor to see how properties change the behavior of the component.
Global component configuration
The MgtPersonCardConfig class exposes static configuration properties that configure all person card components in the application. The class configures what sections and what APIs are used by the person card to fetch details about a user from Microsoft Graph.
By default, all sections and APIs are enabled. The following example shows how to use the class properties to disable sections or APIs.
import { MgtPersonCardConfig } from '@microsoft/mgt-components';
MgtPersonCardConfig.useContactApis = false;
MgtPersonCardConfig.sections.profile = false;
MgtPersonCardConfig.sections.files = false;
The following properties are available.
| Property | Description |
|---|---|
| useContactApis | boolean - Indicates whether the person card component can use Microsoft Graph Contact API to search for contact details and photos. Default value is true. |
| sections | object - Configures what sections are shown in the person card. |
| isSendMessageVisible | boolean - Indicates whether the send message button is visible. Default value is true. |
Person card sections
The person card contains several configurable sections for displaying person details:
- Contact - Contact information such as email, phone, position, location, and more.
- Organization - Organizational graph with managers, direct reports, and relevant people.
- Messages - Most relevant email messages with the current signed in user.
- Files - Most relevant shared files with the current signed in user.
- Profile - Profile information such as projects, skills, languages, and more.
Sections are loaded by default, but they can be disabled globally via the MgtPersonCardConfig.sections object property. The following properties are available.
| Property | Description |
|---|---|
| organization | boolean - Indicates whether the person card organization section is shown. Default value is true. |
| mailMessages | boolean - Indicates whether the person card messages section is shown. Default value is true. |
| files | boolean - Indicates whether the person card files section is shown. Default value is true. |
| profile | boolean - Indicates whether the person card profile section is shown. Default value is true. |
| lock-tab-navigation | boolean - Allows the locking of navigation using tabs so that it doesn't flow out of the card section. Default value is false. |
To disable a section, set the property to false in your app initialization code:
import { MgtPersonCardConfig } from '@microsoft/mgt-components';
MgtPersonCardConfig.sections.profile = false;
Setup for Teams integrations
The Person-Card component allows the user to contact the target person, including via Teams chat. If using the component inside a Teams tab app, you can ensure that the component deep links directly to a chat instead of opening a browser window by setting the microsoftTeamsLib in TeamsHelper.
If the Person-Card component is unable to detect the Teams lib, the component attempts to open the Teams web client instead.
import * as microsoftTeams from "@microsoft/teams-js";
import { TeamsHelper } from "@microsoft/mgt-element";
TeamsHelper.microsoftTeamsLib = microsoftTeams;
Properties
By default, the mgt-person component passes the person details to the mgt-person-card component. However, you can use these attributes to change it when templating the mgt-person component or when using the mgt-person-card component as a standalone component.
| Attribute | Type | Description |
|---|---|---|
| person-details | MicrosoftGraph.User MicrosoftGraph.Person MicrosoftGraph.Contact |
Person object as defined by Microsoft Graph, containing details related to the user. |
| person-image | String | Image uri related to the person displayed in the card. |
| inherit-details | None | Allows person-card to walk parent tree for mgt-person component to use the same person-details and person-image data. |
| user-id | String | Allows developers to supply user-ID to retrieve data shown on person-card component |
| person-query | String | Allows developers to supply person-query to retrieve data shown on person-card component |
| person-card | String | Specifies whether the person-card component can be shown as a pop-up card when you hover or click on the mgt-person component. The allowed values are hover or click. |
CSS custom properties
The mgt-person-card component defines the following CSS custom properties.
<mgt-person-card class="person-card" person-query="me"></mgt-person-card>
.person-card {
--person-card-nav-back-arrow-hover-color: green;
--person-card-icon-color: red;
--person-card-line1-font-size: 30px;
--person-card-line1-font-weight: 800;
--person-card-line1-line-height: 38px;
--person-card-line2-font-size: 24px;
--person-card-line2-font-weight: 600;
--person-card-line2-line-height: 30px;
--person-card-line3-font-size: 24px;
--person-card-line3-font-weight: 300;
--person-card-line3-line-height: 29px;
--person-card-avatar-size: 85px;
--person-card-details-left-spacing: 25px;
--person-card-avatar-top-spacing: 25px;
--person-card-details-bottom-spacing: 20px;
--person-card-background-color: pink;
--person-card-expanded-background-color-hover: blue;
--person-card-icon-hover-color: magenta;
--person-card-show-more-color: blue;
--person-card-show-more-hover-color: green;
--person-card-fluent-background-color: yellow;
--person-card-line1-text-color: purple;
--person-card-line2-text-color: blue;
--person-card-line3-text-color: green;
--person-card-fluent-background-color-hover: orange;
--person-card-base-icons-left-spacing: 110px;
/** person-card sections tokens */
/** Organization */
--organization-active-org-member-target-background-color: blue;
--organization-title-color: green;
--organization-sub-title-color: yellow;
--organization-hover-color: grey;
--organization-coworker-hover-color: grey;
--organization-coworker-border-color: purple;
--organization-active-org-member-border-color: red;
--organization-coworker-person-avatar-size: 50px;
--organization-member-person-avatar-size: 60px;
--organization-direct-report-person-avatar-size: 80px;
/** Style for the avatar-size in the person-card sections */
--organization-member-person-avatar-size: 60px;
--coworker-person-avatar-size: 50px;
--direct-report-person-avatar-size: 40px;
/** Files: Uses custom css properties for mgt-file-list and mgt-file */
/** Messages */
--message-subject-color: purple;
--message-from-color: blue;
--message-color: black;
--message-hover-color: grey;
--message-subject-font-size: 18px;
--message-subject-font-weight: 600;
--message-subject-line-height: 25px;
--message-from-font-size: 40px;
--message-from-font-weight: 800;
--message-date-color: purple;
--message-from-line-height: 25px;
/** Contact */
--contact-title-color: blue;
--contact-value-color: green;
--contact-link-color: red;
--contact-link-hover-color: purple;
--contact-background-color: grey;
--contact-copy-icon-color: yellow;
/** Profile */
--profile-title-color: blue;
--profile-background-color: grey;
--profile-token-item-color: blue;
--profile-token-overflow-color: purple;
--profile-section-title-color: black;
--profile-token-item-background-color: yellow;
}
To learn more, see styling components.
Templates
The Person-Card component uses templates that allow you to add or replace portions of the component. To specify a template, include a <template> element inside of a component and set the data-type to one of the following values.
| Data type | Data context | Description |
|---|---|---|
| no-data | null | The template used when no 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-details | person: The person details object |
The template used to render the top part of the person card. |
| additional-details | person: The person details object personImage: the URL of the image |
The template used to add custom content to the additional details container. |
For example, you can use a template to customize the component attached to the mgt-person component and a template to add additional details to the card.
<mgt-person person-query="me" view="twolines" person-card="hover">
<template data-type="person-card">
<mgt-person-card inherit-details>
<template data-type="additional-details">
<h3>Stuffed Animal Friends:</h3>
<ul>
<li>Giraffe</li>
<li>lion</li>
<li>Rabbit</li>
</ul>
</template>
</mgt-person-card>
</template>
</mgt-person>
Events
The following events are fired from the component.
| Event | When is it emitted | Custom data | Cancelable | Bubbles | Works with custom template |
|---|---|---|---|---|---|
expanded |
The user opened the expanded details section of the card | None | No | Yes | Yes, unless you override the default template |
For more information about handling events, see events.
Microsoft Graph permissions
The Person-Card control uses the following Microsoft Graph APIs and permissions. For each API called, the user must have at least one of the permissions listed.
| Configuration | Permission | API | Section |
|---|---|---|---|
| In all configurations | User.Read, User.ReadWrite | /me | Default |
personDetails set with user's id but without e-mail, or userId set |
User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All | /users/{id} | Default |
personDetails set with user's id but without e-mail, or userId set |
User.ReadBasic.All, User.Read.All, User.ReadWrite.All | /users/{id}/photo/$value | Default |
personQuery set to me |
User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All | /me, /users/{id}/photo/$value | Default |
personQuery set to me |
User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All | /me/photo/$value | Default |
personQuery set to a value different than me |
People.Read, People.Read.All | /me/people/?$search= | Default |
personQuery set to a value different than me and config.useContactApis set to true (default) |
Contacts.Read, Contacts.ReadWrite | /me/contacts/* | Default |
personQuery set to a value different than me and config.useContactApis set to false |
User.ReadBasic.All, User.Read.All, User.ReadWrite.All | /users/{id}/photo/$value | Default |
showPresence set to true |
Presence.Read.All | /users/{id}/presence | Default |
sections.organization enabled (default) |
User.ReadBasic.All, User.Read.All, Directory.Read.All, User.ReadWrite.All, Directory.ReadWrite.All | /users/{id}?$expand=manager($levels=max), /users/${id}/directReports | Organization |
sections.organization.showWorksWith set (default) |
People.Read.All | /users/{id}/people | Organization |
sections.mailMessages enabled (default) |
Mail.ReadBasic, Mail.Read, Mail.ReadWrite | /me/messages | Messages |
sections.files enabled (default) |
Sites.Read.All, Sites.ReadWrite.All | /me/insights/shared and /me/insights/used | Files |
sections.profile enabled (default) |
User.Read.All, User.ReadWrite.All | /users/{id}/profile | Profile |
The getMgtPersonCardScopes() function returns an array of scopes required for the person card to function based on the global person card configuration.
import { getMgtPersonCardScopes } from `@microsoft/mgt-components`;
const neededScopes = getMgtPersonCardScopes();
Subcomponents
The mgt-person-card 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:
Authentication
The Person-Card control uses the global authentication provider described in the authentication documentation.
Cache
Important
The mgt-person-card component retrieves the basic person data from the parent mgt-person component without calling Microsoft Graph. When mgt-person-card is used separately, it retrieves the necessary data itself and caches it. The data displayed in the card's sections is retrieved separately and isn't cached.
| Object store | Cached data | Remarks |
|---|---|---|
people |
Person's information | Used when personQuery is specified and its value is different than me |
photos |
Person's photo | |
presence |
Person's presence | Used, when showPresence is set to true |
users |
Person's user information | Used when userId is specified or the personQuery is set to me |
For more information about how to configure the cache, see Caching.
Localization
The control exposes the following variables that can be localized. For details about how to set up localization, see Localizing components.
| String name | Default value |
|---|---|
| endOfCard | End of the card |
| quickMessage | Send a quick message |
| expandDetailsLabel | Expand details |
| renderOverviewSectionLabel | Render overview section |
| sendMessageLabel | Send message |
| emailButtonLabel | Email |
| callButtonLabel | Call |
| chatButtonLabel | Chat |
| videoButtonLabel | Video |
| closeCardLabel | Close card |
You can also localize the following variables in the person-card sections.
Contact
| String name | Default value |
|---|---|
| contactSectionTitle | Contact |
| emailTitle | Email |
| chatTitle | Teams |
| businessPhoneTitle | Business Phone |
| cellPhoneTitle | Mobile Phone |
| departmentTitle | Department |
| personTitle | Email |
| officeLocationTitle | Office Location |
| copyToClipboardButton | Copy to clipboard |
Files
| String name | Default value |
|---|---|
| showMoreSubtitle | Show more items |
| filesSectionTitle | Files |
| sharedTextSubtitle | Shared |
Messages
| String name | Default value |
|---|---|
| emailsSectionTitle | Emails |
Organization
| String name | Default value |
|---|---|
| reportsToSectionTitle | Reports to |
| directReportsSectionTitle | Direct reports |
| organizationSectionTitle | Organization |
| youWorkWithSubSectionTitle | You work with |
| userWorksWithSubSectionTitle | works with |
Profile
| String name | Default value |
|---|---|
| SkillsAndExperienceSectionTitle | Skills & Experience |
| AboutCompactSectionTitle | About |
| SkillsSubSectionTitle | Skills |
| LanguagesSubSectionTitle | Languages |
| WorkExperienceSubSectionTitle | Work Experience |
| EducationSubSectionTitle | Education |
| professionalInterestsSubSectionTitle | Professional Interests |
| personalInterestsSubSectionTitle | Personal Interests |
| birthdaySubSectionTitle | Birthday |
| currentYearSubtitle | Current |
| socialMediaSubSectionTitle | Social Media |