Microsoft Graph Toolkit (MGT)

The Microsoft Graph Toolkit is a collection of reusable, framework-agnostic web components and authentication providers designed to simplify accessing and working with Microsoft Graph.

Components are fully functional out of the box and can be used in standard HTML/JavaScript or via React wrappers. Providers handle the authentication and token acquisition required to fetch data from Microsoft Graph APIs.

The Microsoft Graph Toolkit (MGT) is a collection of reusable, framework-agnostic web components and authentication providers designed to work with Microsoft Graph APIs.

Key features include:

• Components: Pre-built web components for common Microsoft Graph experiences (e.g., agenda, files, people, tasks).
• Providers: Implementations for authentication and token acquisition (e.g., MSAL 2.0, SharePoint, TeamsFx).
• Framework Support: While components are web components, they are also available as React components via @microsoft/mgt-react.

The @microsoft/mgt package acts as a convenience bundle that includes all MGT packages except for the React wrapper.

The mgt-login component provides a UI for Microsoft Identity Platform authentication. It automatically switches between two states:

1. Signed out: Displays a sign-in button.
2. Signed in: Displays the active user's display name and profile photo/avatar. Clicking it opens a flyout containing profile data for all signed-in accounts and a sign-out option.

Multi-account support: If used with a provider that supports multiple accounts (like MSAL 2.0), the flyout will include an option to "add another account" and allow users to switch between signed-in accounts. Switching accounts updates the active account context for all other Toolkit components on the page.

Note: The component uses Person components internally to represent users.

<!-- Example with MSAL 2.0 Provider -->
<mgt-msal2-provider client-id="123"></mgt-msal2-provider>
<mgt-login></mgt-login>

The mgt-file-picker component provides a user interface for selecting files from OneDrive or SharePoint. It includes a button that opens a dropdown list of files (rendered using mgt-file components) and a "See all" button to launch a full file browsing experience. When a user selects a file, the component returns the selected file object(s) to the developer via the filesSelected event.

<!-- Example: Show the user's top 10 most recently used files -->
<mgt-file-picker insight-type="used" show-max="10"></mgt-file-picker>

The mgt-picker is a component that queries a Microsoft Graph API endpoint and renders a dropdown control for selecting a single resource. It can also support predefined lists of resources that do not require a Microsoft Graph query.

Common use cases include selecting a To Do list or any other resource from an endpoint that returns an array of items.

<mgt-picker resource="/groups"></mgt-picker>

The mgt-file-list component displays a list of folders and files using names, icons, and other properties. It leverages the mgt-file component to render individual items. You can configure it to show files from a specific drive, site, or based on user insights (trending, used, or shared), or provide custom queries.

<mgt-file-list></mgt-file-list>

The ProxyProvider class allows a developer to proxy all calls to Microsoft Graph to their own backend.

Use Case: Use this when authentication and Microsoft Graph calls must be handled on the backend rather than directly from the client. This ensures that all Microsoft Graph Toolkit (mgt) components function correctly by routing their requests through your controlled proxy endpoint.

Disambiguation allows you to use a specific version of MGT in your SPFx solution without colliding with other solutions on the same page. By disambiguating tag names, you avoid conflicts with other developers' components.

Important Requirements:

1. Unique Value: Use a disambiguation value unique to your organization and solution (e.g., contoso-hr-extensions) to prevent collisions.
2. Helper Function: You must use customElementHelper.withDisambiguation('your-unique-id') to allow the creation of disambiguated tag names.
3. Tag Format: The resulting HTML tags will follow the pattern <mgt-[disambiguation-id]-[component-name]>.

Since v4.0.0, components must be explicitly registered to support tree shaking. Instead of importing all components, use the specific registration function for each component you need. The pattern is registerMgt{Name}Component().

Note that some registration functions handle dependencies automatically. For example, registerMgtLoginComponent() also registers mgt-person internally.