Version: Next

Bottom tabs

Bottom tabs refers to a row of links, displayed at the bottom of the screen, and is referred to as "Tab Bar" in iOS and as "Bottom Navigation Bar" on Android. Usually these are intended to be used to switch between top-level content views with a single tap.

Creating bottom tabs#

BottomTabs provide flat navigation and access to up to five equally important top-level root destinations. While any type of layout can be displayed in a tab, typically, Stacks are used, since they allow for vertical navigation within a tab.

Example#

Lets see how to create a simple BottomTabs layout. There are a few things to notice here:

Each child represents a tab on the screen.
The root layout for each tab is a stack to allow for vertical navigation within the tab.
Each stack declares bottomTab options which are used to configure the tab's text, icon, color etc.

bottomTabs: {
  id: 'BOTTOM_TABS_LAYOUT',
  children: [
    {
      stack: {
        id: 'HOME_TAB',
        children: [
          {
            component: {
              id: 'HOME_SCREEN',
              name: 'HomeScreen'
            }
          }
        ],
        options: {
          bottomTab: {
            icon: require('./home.png')
          }
        }
      }
    },
    {
      stack: {
        id: 'PROFILE_TAB',
        children: [
          {
            component: {
              id: 'PROFILE_SCREEN',
              name: 'ProfileScreen'
            }
          }
        ],
        options: {
          bottomTab: {
            icon: require('./profile.png')
          }
        }
      }
    }
  ]
}

Once we run this code, our BottomTabs should look like this:

Selecting Tabs Programmatically#

Tabs can be selected programmatically by updating the currentTabIndex or currentTabId options.

We'll use the BottomTabs layout showcased above to demonstrate programmatic tab selection.

Selecting a tab by index#

The following mergeOptions command will select the second tab. We're passing the id of our BottomTabs layout, but we could also use the id of any of the child components, for example PROFILE_TAB or PROFILE_SCREEN.

Navigation.mergeOptions('BOTTOM_TABS_LAYOUT', {
  bottomTabs: {
    currentTabIndex: 1
  }
});

Selecting a tab by id#

Tabs can also be selected by id (componentId). This is particularly useful in cases where you don't know in which tab a screen is contained. For example, if invoked from one of the child components, HOME_SCREEN or SETTINGS_SCREEN, the following merge command will select the tab containing the child.

Navigation.mergeOptions(this.props.componentId, {
  bottomTabs: {
    currentTabId: this.props.componentId
  }
});

Changing BottomTabs visibility#

The visible property is used to control the BottomTab visibility. Visibility can be toggled dynamically using the mergeOptions command.

Navigation.mergeOptions(componentId, {
  bottomTabs: {
    visible: false
  },
});

Visibility can also be changed when pushing screens.

Navigation.push(componentId, {
  component: {
    name: 'pushedScreen',
    options: {
      bottomTabs: {
        visible: false
      }
    }
  }
});

Updating tab options dynamically#

To update a tab option, like an icon, text or color, simply call mergeOptions with new options using the id of a component or layout contained in the tab you wish to update.

For instance, in the example below we update the color of a specific tab:

Navigation.mergeOptions(componentId, {
  bottomTab: {
    iconColor: 'red',
    textColor: 'red'
  },
});

Styling the tabs#

The bottom-tabs feature support for an enhanced, floating-like layout that offers a modern and visually appealing alternative to the default design. This layout creates the illusion of the tabs hovering above the screen content, adding depth and sophistication to the user interface.

To achieve this effect (and fully customize it), you can use the following bottom-tabs styling options:

Navigation.setRoot({ // An example; push() also support this
  root: {
    bottomTabs: {
      options: {
        layoutStyle: 'compact',
        translucent: true,
        drawBehind: true,
        bottomMargin: 15,

        // Cosmetics:
        cornerRadius: 15,
        blurRadius: 2.0, // Actual radius would be 2.0 * 4 = 8.0
        backgroundColor: 'rgba(50, 50, 50, 0.4)', // A subtle semi-transparent (40%) hue
        elevation: 1, // Soft surrounding shadow effect (i.e. the elevation)
      },
      children: [
        // ...
      ],
    },
  },
});

Setting layoutStyle: compact keeps the tabs container from taking up the entire screen width, thus leaving room for the screen content to appear on both its sides.
The translucent property adds a semi-transparent background, while drawBehind and bottomMargin allow the screen content to flow beneath the hovering tabs.
The cornerRadius rounds the edges of the tabs, giving them a soft, card-like appearance.

Note: Settings some of the options via mergeOptions is discouraged, as they'd only apply for the currently visible tab.

Controlling tab loading#

By default, all tabs are mounted at the same time. This can have a negative impact on performance since screens which are not visible to the user are mounted.

The order in which tabs are mounted can be configured with the tabsAttachMode option:

together - all tabs are mounted at the same time, this is the default behavior.
afterInitialTab - after initial tab is mounted, other tabs are mounted.
onSwitchToTab - initial tab is mounted, other tabs are mounted when the user navigates to them for the first time.