|
| 1 | +# React wrapper for Microsoft Graph Toolkit |
| 2 | + |
| 3 | +[](https://www.npmjs.com/package/@microsoft/mgt-react) |
| 4 | + |
| 5 | +Use `mgt-react` to simplify usage of [Microsoft Graph Toolkit (mgt)](https://aka.ms/mgt) web components in React. The library wraps all mgt components and exports them as React components. |
| 6 | + |
| 7 | +`mgt-react` extends [`wc-react`](https://github.com/nmetulev/wc-react) adding support for templates. |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +```bash |
| 12 | +npm install @microsoft/mgt-react |
| 13 | +``` |
| 14 | + |
| 15 | +or |
| 16 | + |
| 17 | +```bash |
| 18 | +yarn add @microsoft/mgt-react |
| 19 | +``` |
| 20 | + |
| 21 | +## Usage |
| 22 | + |
| 23 | +Import a component at the top: |
| 24 | + |
| 25 | +```tsx |
| 26 | +import { Person } from '@microsoft/mgt-react'; |
| 27 | +``` |
| 28 | + |
| 29 | +You can now use `Person` anywhere in your JSX as a regular React component. |
| 30 | + |
| 31 | +```tsx |
| 32 | +<Person personQuery="me" /> |
| 33 | +``` |
| 34 | + |
| 35 | +### Use properties instead of attributes |
| 36 | + |
| 37 | +For example, you can set the `personDetails` property to an object: |
| 38 | + |
| 39 | +```jsx |
| 40 | +const App = (props) => { |
| 41 | + const personDetails = { |
| 42 | + displayName: 'Bill Gates', |
| 43 | + }; |
| 44 | + |
| 45 | + return <Person personDetails={personDetails}></Person>; |
| 46 | +}; |
| 47 | +``` |
| 48 | + |
| 49 | +### Register event handlers: |
| 50 | + |
| 51 | +```jsx |
| 52 | +import { PeoplePicker } from '@microsoft/mgt-react'; |
| 53 | + |
| 54 | +const App = (props) => { |
| 55 | + handleSelectionChanged = (e) => { |
| 56 | + this.setState({ people: e.target.selectedPeople }); |
| 57 | + }; |
| 58 | + |
| 59 | + return <PeoplePicker selectionChanged={this.handleSelectionChanged} />; |
| 60 | +}; |
| 61 | +``` |
| 62 | + |
| 63 | +All properties and events map exactly as they are defined on the web component - [see web component docs](https://aka.ms/mgt-docs). |
| 64 | + |
| 65 | +### Templates |
| 66 | + |
| 67 | +`mgt-react` allows you to leverage React for writing templates for mgt components. |
| 68 | + |
| 69 | +> Note: You can learn more about [templating mgt components here](https://docs.microsoft.com/graph/toolkit/templates) |
| 70 | +
|
| 71 | +For example, to create a template to be used for rendering events in the `mgt-agenda` component, first define a component to be used for rendering an event: |
| 72 | + |
| 73 | +```tsx |
| 74 | +import { MgtTemplateProps } from '@microsoft/mgt-react'; |
| 75 | + |
| 76 | +const MyEvent = (props: MgtTemplateProps) => { |
| 77 | + const { event } = props.dataContext; |
| 78 | + return <div>{event.subject}</div>; |
| 79 | +}; |
| 80 | +``` |
| 81 | + |
| 82 | +Then use it as a child of the wrapped component and set the template prop to `event` |
| 83 | + |
| 84 | +```tsx |
| 85 | +import { Agenda } from '@microsoft/mgt-react'; |
| 86 | + |
| 87 | +const App = (props) => { |
| 88 | + return <Agenda> |
| 89 | + <MyEvent template="event"> |
| 90 | + </Agenda> |
| 91 | +} |
| 92 | +``` |
| 93 | + |
| 94 | +The `template` prop allows you to specify which template to overwrite. In this case, the `MyEvent` component will be repeated for every event, and the `event` object will be passed as part of the `dataContext` prop. |
| 95 | + |
| 96 | +## What components can I use? |
| 97 | + |
| 98 | +The library is auto generated from the Microsoft Graph Toolkit and all components are available. |
| 99 | + |
| 100 | +The names of the React components are in PascalCase and do not include the `Mgt` prefix. For example, the `mgt-person` component is available as `Person`, and the `mgt-people-picker` component is available as `PeoplePicker`. See the [Microsoft Graph Toolkit documentation](https://aka.ms/mgt-docs) for a list of all components. |
| 101 | + |
| 102 | +## Why |
| 103 | + |
| 104 | +If you've used web components in React, you know that proper interop between web components and React components requires a bit of extra work. |
| 105 | + |
| 106 | +From [https://custom-elements-everywhere.com/](https://custom-elements-everywhere.com/): |
| 107 | + |
| 108 | +> React passes all data to Custom Elements in the form of HTML attributes. For primitive data this is fine, but the system breaks down when passing rich data, like objects or arrays. In these instances you end up with stringified values like some-attr="[object Object]" which can't actually be used. |
| 109 | + |
| 110 | +> Because React implements its own synthetic event system, it cannot listen for DOM events coming from Custom Elements without the use of a workaround. Developers will need to reference their Custom Elements using a ref and manually attach event listeners with addEventListener. This makes working with Custom Elements cumbersome. |
0 commit comments