# Titanium.UI.TabGroup

A tabbed group of windows.

Availability

0.9

9.2.0

Extends

Titanium.UI.Window

# Overview

A tab group can contain one or more Titanium.UI.Tab objects, each of which has an associated tab control that is used to bring it into focus.

Use the Titanium.UI.createTabGroup method or <TabGroup> Alloy element to create a tab group that, in turn, contains one or more <Tab> elements.

You can add tabs to the group using Titanium.UI.TabGroup.addTab, and programmatically switch to a specific tab using Titanium.UI.TabGroup.setActiveTab.

# Platform Implementation Notes

When using a tab group, note the following differences between platforms:

The tab group controls are positioned at the top of the display on Android and at the bottom on iOS.
On Android, only one tab group may exist at one time. A tab group may be closed to allow a new one to be opened later, but the root of the application must be a heavyweight window to prevent it exiting. Tabs cannot be removed from the tab group once added, and tabs cannot be reordered.
On iOS, more than one tab group may exist, and may be opened and closed as required. Each tab can contain a stack of windows, and the user can switch between them by tapping the tab's associated control. Tabs can be removed, and the user may (optionally) be allowed to reorder tabs.
On iOS, it is also possible to add tabs by updating the Titanium.UI.TabGroup.tabs property, and to switch active tabs by setting the Titanium.UI.Tab.active property on one of the tabs to true. Since these mechanisms are platform-specific, it is recommended that you use addTab and setActiveTab instead.
If you use the iOS-specific mechanisms, it is possible to add multiple active tabs to a tab group. In this case, the result of which tab is initially selected is undefined.

# Further Reading

If using tab groups on iOS, see iOS UI Element Usage Guidelines (opens new window).

# Examples

# Alloy XML Markup

Default Titanium project as an Alloy view.

<Alloy>
    <TabGroup backgroundColor="white" >
        <Tab id="tab1" title="Tab 1" icon="KS_nav_views.png">
            <Window id="win1" title="Tab 1">
                <Label id="label1" color="#999">I am Window 1</Label>
            </Window>
        </Tab>
        <Tab id="tab2" title="Tab 2" icon="KS_nav_views.png">
            <Window id="win2" title="Tab 2">
                <Label id="label2" color="#999">I am Window 2</Label>
            </Window>
        </Tab>
        <!-- Use the Require tag to include external Ti.UI.Tab views -->
    </TabGroup>
</Alloy>

# Classic Titanium Example

Simple two-tabbed app.

var win1 = Ti.UI.createWindow({
    backgroundColor: 'blue',
    title: 'Blue'
});
win1.add(Ti.UI.createLabel({text: 'I am a blue window.'}));

var win2 = Ti.UI.createWindow({
    backgroundColor: 'red',
    title: 'Red'
});
win2.add(Ti.UI.createLabel({text: 'I am a red window.'}));

var tab1 = Ti.UI.createTab({
    window: win1,
    title: 'Blue'
}),
tab2 = Ti.UI.createTab({
    window: win2,
    title: 'Red'
}),
tabGroup = Ti.UI.createTabGroup({
    tabs: [tab1, tab2]
});
tabGroup.open();

# Properties

# activeTab

Availability

0.9

9.2.0

activeTab :Number | Titanium.UI.Tab

Active tab.

# activeTabBackgroundImage

Availability

3.1.0

9.2.0

activeTabBackgroundImage :String

Default background image for the active tab.

# activeTabIconTint DEPRECATED

Availability

3.1.0

9.2.0

activeTabIconTint :String | Titanium.UI.Color

DEPRECATED SINCE 9.0.3

Deprecated in favor of activeTintColor or alternatively activeTintColor.

Color applied to active tabs icons, as a color name or hex triplet, where the tab's activeIcon was not defined.

For information about color values, see the "Colors" section of Titanium.UI.

# activeTintColor

Availability

9.0.3

9.2.0

activeTintColor :String

The activeTintColor to apply to tabs.

This property affects the tint of selected tab icons.

Default: null

# activeTitleColor

Availability

9.0.3

9.2.0

activeTitleColor :String | Titanium.UI.Color

Defines the color of the title of tab when it's active.

The color of the title of the tab when it's active.

# activity READONLY

Availability

3.0.0

activity :Titanium.Android.Activity

Reference to the Android Activity object associated with this tab group.

An Activity object is not created until the tab group opens. Before the tab group opens, activity refers to an empty JavaScript object. You can set properties on this object but cannot invoke any Activity methods on it. Once the tab group opens, the actual Activity object is created, using any properties set on the JavaScript object. At this point, you can call methods on the activity and access any properties that are set when the activity is created.

Prior to Release 3.4.0, you can only set properties on the activity after the tab group opens.

# allowUserCustomization

Availability

0.9

9.2.0

allowUserCustomization :Boolean

Allow the user to reorder tabs in the tab group using the Edit button on the More tab.

Set to false to prevent tab reordering.

Default: true

# barColor

Availability

8.0.1

0.9

9.2.0

barColor :String | Titanium.UI.Color

Default navigation bar color (typically for the More tab), as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

A value of transparent results in a semi-opaque black bar style.

# editButtonTitle

Availability

0.9

9.2.0

editButtonTitle :String

Title for the edit button on the More tab.

# exitOnClose

Availability

0.9

exitOnClose :Boolean

Boolean value indicating if the application should exit when closing the tab group, whether via Android back button or the close method.

Starting in 3.4.2 you can set this property at any time. In earlier releases you can only set this as a createTabGroup({...}) option.

Default: True if tab group is opened on top of the root activity. False otherwise.

# navTintColor

Availability

3.3.0

9.2.0

navTintColor :String | Titanium.UI.Color

The tintColor to apply to the navigation bar (typically for the More tab).

This property is a direct correspondant of the tintColor property of NavigationBar on iOS.

Default: null

# paddingBottom

Availability

10.1.0

paddingBottom :Number | String

Bottom padding of bottom navigation

When using TABS_STYLE_BOTTOM_NAVIGATION you can set the padding to have a floating bottom navigation

# paddingLeft

Availability

10.1.0

paddingLeft :Number | String

Left padding of bottom navigation

When using TABS_STYLE_BOTTOM_NAVIGATION you can set the padding to have a floating bottom navigation

# paddingRight

Availability

10.1.0

paddingRight :Number | String

Right padding of bottom navigation

When using TABS_STYLE_BOTTOM_NAVIGATION you can set the padding to have a floating bottom navigation

# shadowImage

Availability

3.1.0

9.2.0

shadowImage :String

Image of the shadow placed between the tab bar and the content area.

The tabsBackgroundImage property must also be set in order for this to take effect.

# shiftMode

Availability

8.0.0

shiftMode :Boolean

Determines whether the TABS_STYLE_BOTTOM_NAVIGATION uses shiftMode.

In Android BottomNavigationView uses shiftMode by default. This mode changes unselected tabs' properties - makes the title invisible and reduces the icon's dimensions by half.

This property allows the user to choose whether they would use this design behavior.

NOTE: This property only affects TabGroups with the TABS_STYLE_BOTTOM_NAVIGATION.

Default: true

# smoothScrollOnTabClick

Availability

3.6.0

smoothScrollOnTabClick :Boolean

Boolean value indicating if changing pages by tab clicks is animated.

If true, when clicking the tab the page transition is animated, false otherwise.

Default: true

# style CREATION ONLY

Availability

8.0.0

style :Number

Property defining which style for the TabGroup to be used.

Since 8.0.0 Titanium has introduce a new style to be used for the TabGroup component.

For backwards compatibility not taking advantage of this property results in using the default style which is similar to the ActionBar Tabs style but sticking to the Material design Guidelines.

TABS_STYLE_DEFAULT is the style that was used in Titanium prior to 8.0.0.GA. It displays the TabGroup with a list of Tabs at the top of the screen.

TABS_STYLE_BOTTOM_NAVIGATION is a style that displays the TabGroup with a list of Tabs in a controller at the bottom of the screen. The recommended usage of this style is for items count between three and five: (https://material.io/design/components/bottom-navigation.html#usage) In Android it is limited to supporting a maximum number of five tabs. You can use paddingLeft, paddingRight, paddingBottom to create a floating bottom navigation. If you want to change the radius or background color you'll need to create /app/platform/android/res/drawable/titanium_rounded_corners.xml and set it to

<?xml version="1.0" encoding="UTF-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android">
    <solid android:color="#FFFFFF" />
    <corners android:radius="7dp" />
</shape>

This API can be assigned the following constants:

# swipeable

Availability

3.6.0

swipeable :Boolean

Boolean value indicating if tab navigation can be done by swipes, in addition to tab clicks.

On Android, the tabs may be selected by swipes, in addition to clicks. This property may be set at tab group creation, or any time later as long as the tab navigation is not disabled.

Default: true

# tabs

Availability

0.9

9.2.0

tabs :Array<Titanium.UI.Tab>

Tabs managed by the tab group.

# tabsBackgroundColor

Availability

3.0.0

9.2.0

tabsBackgroundColor :String | Titanium.UI.Color

Default background color for inactive tabs, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

A tab's backgroundColor property takes precedence if set.

This property applies to all states and tabs, not just inactive tabs. Furthermore, the inactive tab icons without activeIcon will be tinted this color.

# tabsBackgroundImage

Availability

3.1.0

9.2.0

tabsBackgroundImage :String

Default background image for tabs.

# tabsBackgroundSelectedColor

Availability

3.0.0

tabsBackgroundSelectedColor :String

Default background selected color for tabs, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

This property is only supported by TABS_STYLE_BOTTOM_NAVIGATION.

A tab's backgroundFocusedColor property takes precedence if set.

# tabsTintColor DEPRECATED

Availability

3.1.3

9.2.0

tabsTintColor :String | Titanium.UI.Color

DEPRECATED SINCE 9.0.3

Deprecated in favor of tintColor or alternatively tintColor.

The tintColor to apply to the tabs.

This property is a direct correspondant of the tintColor property of UITabBar on iOS. This effects the title and icons rendered in the active tab. When not specified the active icons are tinted with a bright blue.

Default: null

# tabsTranslucent

Availability

6.2.0

9.2.0

tabsTranslucent :Boolean

A Boolean value that indicates whether the tab bar is translucent.

When the value of this property is true, the tab group adds a translucent effect to its background image or tint color. When translucency is enabled, part of the tab bar's underlying content is able to show through, although the amount that shows through depends on the rest of the tab bar configuration. For example, a background image can wholly or partially obscure the background content. Setting this property to NO causes the tab bar to render its bar tint color or background image on top of an opaque backdrop.

The default value of this property is dependent on the configuration of the tab bar:

The default value is true when the tab bar does not have a custom background image.
The default value is true when a custom background image contains any transparency - that is, at least one pixel has an alpha value of less than 1.0.
The default value is false when the custom background image is completely opaque - that is, all pixels have an alpha value of 1.0.

Default: true

# tintColor

Availability

9.0.3

9.2.0

tintColor :String

The tintColor to apply to tabs.

This property affects the tint of unselected tab icons.

Default: null

# title

Availability

3.3.0

title :String

Title for this tabGroup.

# titleAttributes

Availability

3.3.0

9.2.0

titleAttributes :titleAttributesParams

Title text attributes of the window to be applied on the More tab.

Use this property to specify the color, font and shadow attributes of the title.

# titleColor

Availability

9.0.3

9.2.0

titleColor :String | Titanium.UI.Color

Defines the color of the title of tab when it's inactive.

The color of the title of the tab when it's inactive.

# translucent

Availability

3.3.0

9.2.0

translucent :Boolean

Boolean value indicating if the nav bar (typically for the More tab), is translucent.

Default: true on iOS7 and above, false otherwise.

# unselectedItemTintColor DEPRECATED

Availability

6.1.0

9.2.0

unselectedItemTintColor :String | Titanium.UI.Color

DEPRECATED SINCE 9.0.3

Deprecated in favor of tintColor or alternatively tintColor.

Unselected items in this tab group will be tinted with this color. Setting this value to null indicates that the tab group should use its default value instead.

For information about color values, see the "Colors" section of Titanium.UI.

# windowSoftInputMode CREATION ONLY

Availability

0.9

windowSoftInputMode :Number

Determines how the tab group is treated when a soft input method (such as a virtual keyboard) is displayed.

For more information see the official Android API Reference, Window.setSoftInputMode.

This API can be assigned the following constants:

# Methods

# addTab

Availability

0.9

9.2.0

addTab(tab) → void

Adds a tab to the tab group.

Parameters

Name	Type	Description
`tab`	Titanium.UI.Tab	Tab to add.

Returns

Type: void

# close

Availability

0.9

9.2.0

close([params]) → Promise<any>

Closes the tab group and removes it from the UI.

Android only supports the argument type closeWindowParams.

Parameters

Name	Type	Description
`params`	Titanium.UI.Animation \| Dictionary<Titanium.UI.Animation> \| closeWindowParams	Animation or display properties to use when closing the window.

Returns

Starting in SDK 10.0.0, this method returns a Promise that will be resolved once the window is closed, akin to adding a one-time listener for the close event. If the window fails to close (for example, because it was not yet open) the Promise will be rejected.

Type: Promise<any>

# disableTabNavigation

Availability

3.6.0

disableTabNavigation(disable) → void

Disable (or re-enable) tab navigation. If tab navigation is disabled, the tabs are hidden and the last selected tab window is shown.

Parameters

Name	Type	Description
`disable`	Boolean	True to disable tab navigation, false to re-enable the tabs.

Returns

Type: void

# getActiveTab DEPRECATED

Availability

0.9

9.2.0

getActiveTab() → Titanium.UI.Tab

DEPRECATED SINCE 10.0.0

Use the activeTab property instead.

Gets the currently-active tab.

Returns

Type: Titanium.UI.Tab

# getTabs DEPRECATED

Availability

0.9

9.2.0

getTabs() → Array<Titanium.UI.Tab>

DEPRECATED SINCE 10.0.0

Use the tabs property instead.

Gets all tabs that are managed by the tab group.

Returns

Type: Array<Titanium.UI.Tab>

# open

Availability

0.9

9.2.0

open([params]) → Promise<any>

Opens the tab group and makes it visible.

Parameters

Name	Type	Description
`params`	openWindowParams	Animation or display properties to use when opening the window.

Returns

Starting in SDK 10.0.0, this method returns a Promise that will be resolved once the window is opened, akin to adding a one-time listener for the open event. If the window fails to open (for example, because it is already opened or opening) the Promise will be rejected.

Type: Promise<any>

# removeTab

Availability

0.9

9.2.0

removeTab(tab) → void

Removes a tab from the tab group.

Parameters

Name	Type	Description
`tab`	Titanium.UI.Tab	Tab to remove.

Returns

Type: void

# setActiveTab DEPRECATED

Availability

0.9

9.2.0

setActiveTab(indexOrObject) → void

DEPRECATED SINCE 10.0.0

Use the activeTab property instead.

Selects the currently active tab in a tab group.

Parameters

Name	Type	Description
`indexOrObject`	Number \| Titanium.UI.Tab	Index or object of the tab to switch to.

Returns

Type: void

# Events

# focus

Availability

0.9

9.2.0

Fired when this tab group gains focus. On Android, fired when a tab in this tab group gains focus.

On Android, this event also fires when the activity enters the foreground (after the activity enters the resume state).

Properties

Name	Type	Description
index	Number	Index of the current active tab.
previousIndex	Number	Index of the previous active tab.
tab	Titanium.UI.Tab	Active tab.
previousTab	Titanium.UI.Tab	Previous active tab.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# androidback

Availability

3.0.0

Fired when the back button is pressed by the user.

This event is fired when the current tab group's activity detects a back button press by the user to navigate back.

By default this event would trigger the current activity to be finished and removed from the task stack. Subscribing to this event with a listener will prevent the default behavior. To finish the activity from your listener just call the close method of the tab group.

# androidcamera

Availability

3.0.0

Fired when the Camera button is released.

Setting a listener disables the default key handling for this button. To restore default behavior, remove the listener.

# androidfocus

Availability

3.0.0

Fired when the Camera button is half-pressed then released.

Setting a listener disables the default key handling for this button. To restore default behavior, remove the listener.

# androidsearch

Availability

3.0.0

Fired when the Search button is released.

Setting a listener disables the default key handling for this button. To restore default behavior, remove the listener.

# androidvoldown

Availability

3.0.0

Fired when the volume down button is released.

Setting a listener disables the default key handling for this button. To restore default behavior, remove the listener.

# androidvolup

Availability

3.0.0

Fired when the volume up button is released.

Setting a listener disables the default key handling for this button. To restore default behavior, remove the listener.

# blur

Availability

0.9

9.2.0

Fired when this tab group loses focus. On Android, fired when a tab in this tab group loses focus.

On Android, this event also fires before putting the activity in the background (before the activity enters the pause state).

Properties

Name	Type	Description
index	Number	Index of the current active tab. On iOS, a value of `undefined` indicates that the More tab was the active tab.
previousIndex	Number	Index of the previous active tab. On iOS, a value of `undefined` indicates that the More tab was the previous tab.
tab	Titanium.UI.Tab	Active tab.
previousTab	Titanium.UI.Tab	Previous active tab. On iOS, a value of `undefined` indicates that the More tab was the previous tab.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# close

Availability

7.1.0

0.9

9.2.0

Fired when the tab group is closed.

# open

Availability

0.9

9.2.0

Fired when the tab group is opened.

The listener for this event must be defined before this window is opened.

# selected DEPRECATED

Availability

5.1.0

DEPRECATED SINCE 5.2.0

Use focus event instead.

Fired when a tab is selected.

Properties

Name	Type	Description
index	Number	Index of the current active tab.
previousIndex	Number	Index of the previous active tab.
tab	Titanium.UI.Tab	Active tab.
previousTab	Titanium.UI.Tab	Previous active tab.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# unselected DEPRECATED

Availability

5.1.0

DEPRECATED SINCE 5.2.0

Use blur event instead.

Fired when a tab is unselected.

Properties

Name	Type	Description
index	Number	Index of the current active tab. On iOS, a value of `undefined` indicates that the More tab was the active tab.
previousIndex	Number	Index of the previous active tab. On iOS, a value of `undefined` indicates that the More tab was the previous tab.
tab	Titanium.UI.Tab	Active tab.
previousTab	Titanium.UI.Tab	Previous active tab. On iOS, a value of `undefined` indicates that the More tab was the previous tab.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.