Build tabs for Teams

Tabs are Teams-aware webpages embedded in Microsoft Teams. They're simple HTML <iframe\> tags that point to domains declared in the app manifest and can be added as part of a channel inside a team, group chat, or personal app for an individual user. You can include custom tabs with your app to embed your own web content in Teams or add Teams-specific functionality to your web content. For more information, see Teams JavaScript client SDK.

Important

Currently, custom tabs are available in Government Community Cloud (GCC), GCC-High, and Department of Defense (DOD).

We recommend you to use the Teams client SDK via npm package and bundle it with your app as currently Teams client SDK is not available in Government Cloud CDN.

Note

This topic reflects version 2.0.0 of the Microsoft Teams JavaScript client SDK. If you are using an earlier version, refer to the Teams JS SDK overview for guidance on the differences between v1 and v2.

The following image shows personal tabs:

Personal tab

The following image shows Contoso channel tabs:

Channel or group tabs

There are few prerequisites that you must go through before working on tabs.

There are two types of tabs available in Teams, personal and channel or group. Personal tabs, along with personal-scoped bots, are part of personal apps and are scoped to a single user. They can be pinned to the left navigation bar for easy access. Channel or group tabs deliver content to channels and group chats, and are a great way to create collaborative spaces around dedicated web-based content.

You can create a content page as part of a personal tab, channel or group tab, or task module. You can create a configuration page that enables users to configure Microsoft Teams app and use it to configure a channel or group chat tab, a message extension, or an Office 365 Connector. You can permit users to reconfigure your tab after installation and create a tab removal page for your application. When you build a Teams app that includes a tab, you must test how your tab functions on both the Android and iOS Teams clients. Your tab must get context through basic information, locale and theme information, and app.Context.page.id or app.Context.page.subPageId that identifies what is in the tab.

You can build tabs with Adaptive Cards and centralize all Teams app capabilities by eliminating the need for a different backend for your bots and tabs. Stage View is a new UI component that allows you to render the content opened in full screen in Teams and pinned as a tab. The existing link unfurling service is updated, so that it's used to turn URLs into a tab using an Adaptive Card and Chat Services. You can create conversational tabs using conversational sub-entities that allow users to have conversations about sub-entities in your tab, such as specific task, patient, and sales opportunity, instead of discussing the entire tab. You can make changes to tab margins to enhance the developer's experience when building apps. You can drag the tab and place it in the desired position to interchange the tab positions within your personal apps and channel or group chats.

Note

Posts and Files can't be moved from their positions.

Tab features

The tab features are as follows:

  • If a tab is added to an app that also has a bot, the bot is also added to the team.
  • Awareness of Microsoft Azure Active Directory (Azure AD) ID of the current user.
  • Locale awareness for the user to indicate language that is en-us.
  • Single sign-on (SSO) capability, if supported.
  • Ability to use bots or app notifications to deep link to the tab or to a sub-entity within the service, for example an individual work item.
  • The ability to open a task module from links within a tab.
  • Reuse of SharePoint web parts within the tab.

Tabs user scenarios

Scenario: Bring an existing web-based resource inside Teams.
Example: You create a personal tab in your Teams app that presents an informational corporate website to users.

Scenario: Add support pages to a Teams bot or message extension.
Example: You create personal tabs that provide about and help webpage content to users.

Scenario: Provide access to items that your users interact with regularly for cooperative dialogue and collaboration.
Example: You create a channel or group tab with deep linking to individual items.

Understand how tabs work

You can use one of the following methods to create tabs:

Declare custom tab in app manifest

A custom tab is declared in the app manifest of your app package. For each webpage you want included as a tab in your app, you define a URL and a scope. Additionally, you can add the Teams JavaScript client SDK to your page, and call app.initialize() after your page loads. Teams displays your page and provides access to Teams-specific information, for example, the Teams client is running the dark theme.

Whether you choose to expose your tab within the channel or group, or personal scope, you must present an <iframe> HTML content page in your tab. For personal tabs, the content URL is set directly in your Teams app manifest by the contentUrl property in the staticTabs array. Your tab's content is the same for all users.

Note

Teams app doesn't recognize sub iframes. Therefore, it'll not load if there is an iframe within the tab app.

For channel or group tabs, you can also create an additional configuration page. This page allows you to configure content page URL, typically by using URL query string parameters to load the appropriate content for that context. This is because your channel or group tab can be added to multiple teams or group chats. On each subsequent install, your users can configure the tab, allowing you to tailor the experience as required. When users add or configure a tab, a URL is associated with the tab that is presented in the Teams user interface (UI). Configuring a tab simply adds additional parameters to that URL. For example, when you add the Azure Boards tab, the configuration page allows you to choose, which board the tab loads. The configuration page URL is specified by the configurationUrl property in the configurableTabs array in your app manifest.

You can have multiple channels or group tabs, and up to 16 personal tabs per app.

Tools to build tabs

Next step

See also