Skip to main content
Use this API to navigate to a page defined in the tab bar configuration. All non-tab pages in the page stack will be closed.

​
Parameters

PropertyTypeRequiredDescription
urlStringYesPath to the tab bar page (no query parameters allowed)
successFunctionNoCallback on success
failFunctionNoCallback on failure
completeFunctionNoCallback that always executes

​
Code Example

​
Basic Usage

my.switchTab({
  url: 'page/home/index'
});

​
With Callbacks

my.switchTab({
  url: 'page/user/index',
  success() {
    console.log('Switched to user tab');
  },
  fail(err) {
    console.error('Failed to switch tab:', err);
  }
});

​
Configuration

The target page must be defined in app.json: 
{
  "tabBar": {
    "textColor": "#666666",
    "selectedColor": "#108ee9",
    "backgroundColor": "#FFFFFF",
    "items": [
      {
        "pagePath": "page/home/index",
        "name": "Home",
        "icon": "images/home.png",
        "activeIcon": "images/home-active.png"
      },
      {
        "pagePath": "page/user/index",
        "name": "User",
        "icon": "images/user.png",
        "activeIcon": "images/user-active.png"
      }
    ]
  }
}

​
Important Notes

  • The URL cannot include query parameters
  • The first page in tabBar must be the homepage
  • Pages opened via my.navigateTo or my.redirectTo won’t display the tab bar even if defined in tabBar configuration
  • Tab icons should be 60×60px for optimal display

​
Differences from Other Navigation APIs

APIBehavior
my.switchTabNavigates to tab page, closes non-tab pages
my.navigateToOpens new page, keeps current page
my.redirectToReplaces current page
my.reLaunchCloses all pages, opens target page

my.navigateTo

Navigate to a new page

my.setTabBarStyle

Customize tab bar style