Microsoft Teams UI Components - React
This library provides React components styled according to the Microsoft Teams design guidelines found here.
Installation
Currently this package is only distributed via npmjs. To install run the following:
npm install msteams-ui-components-react
Usage
The React bindings get the context in which to render the components from a top level Context component. All MS Teams components in this package must be children (direct or indirect) of this top level component. Here is how you would setup a simple React page:
const microsoftTeams = ;const React = const getContext PrimaryButton TeamsThemeContext ThemeStyle = // Wherever you want to mount the React page in your HTML.var mountPoint = ... Component state = theme: ThemeStyleLight fontSize: 16 ; { // If you are deploying your site as a MS Teams static or configurable tab, you should add ?theme={theme} to // your tabs URL in the manifest. That way you will get the current theme on start up (calling getContext on // the MS Teams SDK has a delay and may cause the default theme to flash before the real one is returned). this; this; // If you are not using the MS Teams web SDK, you can remove this entire if block, otherwise if you want theme // changes in the MS Teams client to propogate to the page, you should leave this here. if this microsoftTeams; microsoftTeams; } { const context = ; return <TeamsThemeContextProvider value=context> <PrimaryButton onClick= >Click Me!</PrimaryButton> </TeamsThemeContextProvider> ; } // Grabs the font size in pixels from the HTML element on your page. private { let sizeStr = window; sizeStr = sizeStr; let fontSize = ; if !fontSize fontSize = 16; return fontSize; } // This is a simple method to check if your webpage is running inside of MS Teams. // This just checks to make sure that you are or are not iframed. private { try return windowself !== windowtop; catch e return true; } // Sets the correct theme type from the query string parameter. private { let theme; this; } // Returns the value of a query variable. private { const query = windowlocationsearch; const vars = query; for const varPairs of vars const pair = varPairs; if === variable return ; return null; } ;
You can also render your own custom components using the MS Teams context in two different ways.
- You can wrap them using the
connectTeamsComponent
function.
const React = const connectTeamsComponent ThemeStyle IITeamsThemeContextProps = const CustomComponentInternal: React.FunctionComponent<ICustomComponentProps & ITeamsThemeContextProps> = { const context ...rest = props; const colors style = context; const styleProps = {}; return <div style=styleProps ...rest>propschildren</div>;}; const CustomComponent = ;
You can now render CustomComponent
like any other normal React component as long as it is a child (direct or indirect) of the TeamsThemeContext
.
Component ... { const context = ; return <TeamsThemeContextProvider value=context> <CustomComponent>Hello</CustomComponent> </TeamsThemeContextProvider> ; } ...
You should see that the Hello text is colored in the brand00
MS Teams color. If you are testing this in MS Teams, you can change the theme in the settings to see this color get updated. If you are running this directly in a browser, you can just add the theme query variable (theme=dark
) to see the color change to the dark variation of brand00
.
- Using the render method of the connected component object.
const ConnectedComponent = Component ... { const context = ; return <TeamsThemeContextProvider value=context> <TeamsThemeContextConsumer> { const context ...rest = props; const colors style = context; const styleProps = {}; return <div style=styleProps ...rest>propschildren</div>; } </TeamsThemeContextConsumer> </TeamsThemeContextProvider> ; } ...
As you can see the only difference is where the render code is placed. Using method (1) lets you organize your subcomponents for re-use whereas (2) is a quick way to get at the context. (The code for (1) actually uses (2) under the covers.)
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.