Edit

Navigate within a tab app

  • Article

The Microsoft Teams JavaScript client library (TeamsJS) provides support for navigation within a tab. This article discusses the options available, which include types of navigation such as between tabs within the app or through use of Teams UI components and the back button.

Note

This topic reflects version 2.0.x of the Microsoft Teams JavaScript client library (TeamsJS). If you are using an earlier version, refer to the TeamsJS library overview for guidance on the differences between the latest TeamsJS and earlier versions.

Tabs provide a great way to enhance the Microsoft Teams experience. You can provide users access to your web application right within Teams using tabs, without having to sign in again. For more information about tabs, and how you can extend personal tabs across Microsoft 365 products, see Build tabs for Teams and Extend a Teams personal tab across Microsoft 365.

The pages capability of the TeamsJS library provides support for navigation between tabs within an app. Specifically, the pages.currentApp namespace offers a function navigateTo(NavigateWithinAppParams) to allow navigation to a specific tab within the current app and a function navigateToDefaultPage() to navigate to the first tab defined in the app's manifest.

The following code illustrates how to navigate to a specific page:

if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateTo({pageId: <pageId>, subPageId:<subPageId>});
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/
    const navPromise = pages.navigateToApp({appId: <appId>, pageId: <pageId>});
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}

The following code illustrates how to navigate to the app's default tab:

if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateToDefaultPage();
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/}

Note

The tab app navigation is supported only in new Teams client.

Use the pages.navigateToApp() function or deep links for tab app navigation.

Configure back button navigation

When an app has multiple tabs, a user can use the Microsoft 365 host app's back button to go backwards through the navigational history. However, the history doesn't include the actions a user performs within a tab. If you want to enhance the back button experience, you can maintain your own internal navigation stack and configure a custom handler for back button selections. This can be accomplished through the registerBackButtonHandler() function in the pages.backStack namespace.

After you register the handler, it helps you to address the navigational request before the system takes action. If the handler is able to manage the request, it should return true so that the system knows no further action is necessary. If the internal stack is empty, it should return false so that the system can call the navigateBack() function instead and take the appropriate action.

Return focus to host app

After the user starts using elements within a tab, by default, the focus remains with the elements of your iFrame until the user selects outside of it. If the iFrame is a part of the user navigating with keyboard shortcuts (the Tab key or the F6 key), you can focus on the host app. You can focus on the host app by using the pages.returnFocus() function. The returnFocus() function accepts a Boolean indicating the direction to advance focus within the host app; true for forward and false for backwards. Generally, forward highlights the search bar and backwards highlights the app bar.

Code sample

Sample name Description Node.js
Tab app navigation Sample code shows how to navigate between tabs within the app. View

See also