# Titanium.UI.Tab > A tab instance for a [TabGroup](https://titaniumsdk.com/docs/sdk/Titanium.UI.TabGroup.md). - Source: https://titaniumsdk.com/docs/sdk/13.0.0/Titanium.UI.Tab - Titanium SDK version: 13.0.0 - Kind: view - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 0.8 - Extends: Titanium.UI.View - Inheritance: Titanium.UI.View > Titanium.Proxy A `TabGroup` tab instance. Each tab includes a button and one or more windows, which holds the "contents" of the tab. Users can select a tab by clicking on the tab button. Use the [Titanium.UI.createTab](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createTab) method or **``** Alloy element to create a tab. Use [TabGroup.setActiveTab](https://titaniumsdk.com/docs/sdk/Titanium.UI.TabGroup.md#setActiveTab) to switch between tabs in a tab group. The behavior of tabs and tab groups follows the platform's native navigation style, which varies significantly between platforms. #### iOS Platform Implementation Notes On iOS, the tab maintains a stack of windows. Windows on top of the stack can partially or totally obscure windows lower in the stack. Calling [open](https://titaniumsdk.com/docs/sdk/Titanium.UI.Tab.md#open) opens a new window on top of the window stack. When a window is closed, either by the user or by code, the window is removed from the stack, making the previous window visible. The root tab window cannot be removed. On iOS the tab controls are generally kept on screen to allow a user to navigate inside the app. Tab controls are hidden when the user is performing a modal task (for example, composing a message). In this case, the app should provide a button in the navigation bar to return to the previous screen. On iOS, the window should also be opened as modal. On iOS, The tab controls can also be hidden by opening the new window with [tabBarHidden](https://titaniumsdk.com/docs/sdk/Titanium.UI.Window.md#tabBarHidden) set to `true`. When closing a tab window in iOS, you should always use the [Tab.close](https://titaniumsdk.com/docs/sdk/Titanium.UI.Tab.md#close) method to ensure that the tab group maintains its navigation state. #### Android Platform Implementation Notes On Android, the tab does not maintain a stack of windows. Calling [open](https://titaniumsdk.com/docs/sdk/Titanium.UI.Tab.md#open) opens a new, heavyweight window, which by default covers the tab group entirely. This seems quite different from the iOS model, but it is the standard model for Android applications. Users can use the **Back** button to close the window and return to the tab group. On Android, tab windows can be closed using either [Tab.close](https://titaniumsdk.com/docs/sdk/Titanium.UI.Tab.md#close) or [Window.close](https://titaniumsdk.com/docs/sdk/Titanium.UI.Window.md#close). Since no window stack is maintained, only a single window opened using [Tab.open](https://titaniumsdk.com/docs/sdk/Titanium.UI.Tab.md#open) can be closed using `Tab.close`. As on iOS, the root tab window cannot be closed. ## Example: Simple Tab Example In this example, we create a simple tab and add it to a tab group. ``` js var window = Ti.UI.createWindow({ title: 'My Tab' }); var tab = Ti.UI.createTab({ window: window, title: 'My Tab', icon: 'myicon.png' }); tabGroup.addTab(tab); ``` ## Example: Alloy XML Markup Previous example an an Alloy view. ``` xml ``` ## Properties ### active - Type: Boolean - Platforms: iPhone, iPad, macOS `true` if this tab is active, `false` if it is not. The tab can be activated by setting the property, but since this property is platform-specific, using [TabGroup.setActiveTab](https://titaniumsdk.com/docs/sdk/Titanium.UI.TabGroup.md#setActiveTab) is recommended instead. ### activeIcon - Type: String - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 3.1.0 Icon URL for this tab when active. If unspecified, iOS uses a tint color to indicate the active tab. See [icon](https://titaniumsdk.com/docs/sdk/Titanium.UI.Tab.md#icon) for more information. If the icon provided is larger than [30 pixels (60 pixels for retina, 90 pixels for super-retina)] (https://developer.apple.com/ios/human-interface-guidelines/icons-and-images/image-size-and-resolution/), this image will be scaled to fit. ### activeIconIsMask - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 3.1.3 - Default: `true` Defines if the active icon property of the tab must be used as a mask. This is the equivalent of the [iconIsMask](https://titaniumsdk.com/docs/sdk/Titanium.UI.Tab.md#iconIsMask) property, but for the active icon. When this is true, the active icon is tinted with the color specified in [tabsTintColor](https://titaniumsdk.com/docs/sdk/Titanium.UI.TabGroup.md#tabsTintColor). When this is false the image is rendered as is, though the title of the tab is still tinted. ### activeTintColor - Type: String - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 9.0.3 Defines the color of the tab icon when it is active. ### activeTitleColor - Type: String | Titanium.UI.Color - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK iPhone 4.1.0, iPad 4.1.0, Android 8.0.0 Defines the color of the title of tab when it's active. The color of the title of the tab when it's active. ### backgroundColor - Platforms: Android - Since: Titanium SDK 3.0.0 Sets the color of the tab when it is inactive. For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). ### backgroundFocusedColor - Platforms: Android - Since: Titanium SDK 3.0.0 Sets the color of the tab when it is focused. On the Android platform, this sets the color of the active tab and is only supported by [TABS_STYLE_BOTTOM_NAVIGATION](https://titaniumsdk.com/docs/sdk/Titanium.UI.Android.md#TABS_STYLE_BOTTOM_NAVIGATION). For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). ### badge - Type: String - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 9.3.0 Badge value for this tab. `null` indicates no badge. On the Android platform you will need to use a Theme with `parent="Theme.MaterialComponents.*"` in order to use a badge. You have to pass a number as a string. Non-numberic characters will not be displayed. On iOS, a badge will only be shown if the tab has been assigned an icon. Text only tabs do not support badges. ### badgeBackgroundColor - Type: String | Titanium.UI.Color - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 12.2.0 If this item displays a badge, this color will be used for the badge's background. If set to null, the default background color will be used instead. For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). ### badgeColor - Type: String | Titanium.UI.Color - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 9.3.0, iPhone 6.1.0, iPad 6.1.0, macOS 9.2.0 - DEPRECATED since 12.2.0. Use [Titanium.UI.Tab.badgeBackgroundColor](Titanium.UI.Tab.badgeBackgroundColor) instead. If this item displays a badge, this color will be used for the badge's background. If set to null, the default background color will be used instead. For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). ### badgeTextColor - Type: String | Titanium.UI.Color - Platforms: Android - Since: Titanium SDK 12.2.0 Set the text color of the badge. For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). ### icon - Type: String - Platforms: Android, iPhone, iPad, macOS Icon URL for this tab. #### iOS Tab Icons On iOS, tab icons are usually white with a transparent background. The system uses a transparent tint color to indicate whether the tab is active or inactive. In the inactive state, the tint color is based on the tab bar's color [tabsBackgroundColor](https://titaniumsdk.com/docs/sdk/Titanium.UI.TabGroup.md#tabsBackgroundColor), which defaults to black. In the active state, the tint color is usually blue. Prior to Titanium 3.1, there was no way to override the default active icon tint. Some icon-related features: * You can specify the active tab's tint color as [activeTabIconTint](https://titaniumsdk.com/docs/sdk/Titanium.UI.TabGroup.md#activeTabIconTint). * You can set separate icon images for the active and inactive states. If [activeIcon](https://titaniumsdk.com/docs/sdk/Titanium.UI.Tab.md#activeIcon) is set, then `icon` is used in the inactive state, and `activeIcon` is used in the active state. **No default tint is applied to either icon.** If the icon provided is larger than [30 pixels (60 pixels for retina, 90 pixels for super-retina)] (https://developer.apple.com/ios/human-interface-guidelines/icons-and-images/image-size-and-resolution/), this image will be scaled to fit if used with activeIcon, and cropped at the bottom otherwise. #### Android Tab Icons Can be used in combination with `iconFamily` in a BottomNavigation setup with `experimental:true`. ### iconFamily - Type: String - Platforms: Android - Since: Titanium SDK 12.7.0 Specifies the font family or specific font to use. When using a BottomNavigation setup with `experimental:true` you can use this property in combination with an `icon` to use an icon-font for the tab icons: ``` js '#tab1': { icon: "\ueac1", iconFamily: "tabler-icons" } ``` ### iconInsets - Type: TabIconInsets - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 5.2.0 - Default: `All insets are zero.` The icon inset or outset for each edge. Use this property for example to center an icon without providing a title. To do that, set the insets to `{ top: 6 }` and/or `{ left: 6 }`. The `right` and `bottom` are calculated internally to prevent the icon from mutating. ### iconIsMask - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 3.1.3 - Default: `true` Defines if the icon property of the tab must be used as a mask. When this property is true, the color data of the image specified as the icon is ignored and the image is used as an alpha mask. When this is false, the color data of the image is preserved. ### tintColor - Type: String - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK iPhone 3.1.3, iPad 3.1.3, Android 9.0.3 Defines the color of the tab icon. ### title - Type: String - Platforms: Android, iPhone, iPad, macOS Title for this tab. ### titleColor - Type: String | Titanium.UI.Color - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK iPhone 4.1.0, iPad 4.1.0, Android 8.0.0 Defines the color of the title of tab when it's inactive. The color of the title of the tab when it's inactive. ### titleid - Type: String - Platforms: Android, iPhone, iPad, macOS Key identifying a string from the locale file to use for the tab title. Only one of `title` or `titleid` should be specified. ### window - Type: Titanium.UI.Window - Platforms: Android, iPhone, iPad, macOS Root-level tab window. All tabs must have at least one root-level tab window. ## Methods ### close - Platforms: Android, iPhone, iPad, macOS Closes the top-level window for this tab. On iOS, this method should be used when closing a window opened from a tab, to correctly maintain the iOS tab group's navigation state. Note that the window to be closed **must** be passed in as a parameter: ``` js myTab.close(tabWin); ``` On Android, this method does **not** take a `window` parameter. ``` js myTab.close(); ``` On Android, if a window has been opened in front of the tab using `Tab.open`, a subsequent call to `Tab.close` is equivalent to calling `close` on that window. No window stack is maintained, so only the most-recently opened window on a given tab can be closed in this way. All platforms accept an optional `options` parameter. The only supported property for this dictionary is the `animated` flag, which specifies whether the window close should be animated. `animated` is true by default. Parameters: - `window` (Titanium.UI.Window): Window to close. This parameter **must** be omitted on Android. - `options` (Object, optional): Dictionary of display and animation settings to use when closing the window. Identical to the `options` parameter to [Window.close](https://titaniumsdk.com/docs/sdk/Titanium.UI.Window.md#close). iOS only supports the **animated** parameter. ### open - Platforms: Android, iPhone, iPad, macOS Opens a new window. On iOS, the new window is opened as the top window in the tab's window stack. On Android, the new window is opened as a new, heavyweight window, obscuring the tab group. Parameters: - `window` (Titanium.UI.Window): Window to open. - `options` (openWindowParams, optional): Dictionary of display and animation settings to use when opening the window. Identical to the `options` parameter to [Window.open](https://titaniumsdk.com/docs/sdk/Titanium.UI.Window.md#open). iOS only supports the **animated** parameter. ### popToRootWindow - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 12.7.0, iPhone 6.2.0, iPad 6.2.0, macOS 9.2.0 Closes all windows that are currently opened inside the tab. Note that only the `close` event of the most recently opened window is fired. Parameters: - `options` (AnimatedOptions, optional): iOS only: Options supporting a single `animated` boolean property to determine whether the windows will be animated while being closed (default: false). Default: `{ animated: false }`. ### setWindow - Platforms: Android, iPhone, iPad, macOS - DEPRECATED since 10.0.0. Set the value of the [window](Titanium.UI.Tab.window) property directly. Sets the root window that appears in the tab. You can only use this method to set the tab's root window before the TabGroup containing this tab is openened, that is, once the TabGroup is displayed, you cannot change the root window that appears in the tab. Parameters: - `window` (Titanium.UI.Window): Root window of the tab. ## Events ### click - Platforms: Android Fired when this tab is clicked in the tab group. ### selected - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 3.5.1, iPhone 5.2.0, iPad 5.2.0 Fired when the tab is selected. Event properties: - `index` (Number): Index of the current active tab. - `previousIndex` (Number): Index of the previous active tab. - `tab` (Titanium.UI.Tab): Current active tab object. - `previousTab` (Titanium.UI.Tab): Previous active tab object. ### unselected - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 3.5.1, iPhone 5.2.0, iPad 5.2.0 Fired when the tab is no longer selected. Event properties: - `index` (Number): Index of the current active tab. - `previousIndex` (Number): Index of the previous active tab. - `tab` (Titanium.UI.Tab): Current active tab object. - `previousTab` (Titanium.UI.Tab): Previous active tab object. ## Inherited members 58 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.0.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener` - [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/13.0.0/Titanium.UI.View.md): `accessibilityDisableLongPress`, `backgroundDisabledColor`, `backgroundDisabledImage`, `backgroundFocusedImage`, `backgroundImage`, `backgroundSelectedColor`, `backgroundSelectedImage`, `clearMotionEffects`, `clipMode`, `convertPointToView`, `dblclick`, `doubletap`, `elevation`, `filterTouchesWhenObscured`, `focus`, `getViewById`, `hiddenBehavior`, `horizontalMotionEffect`, `id`, `insertAt`, `longpress`, `overrideCurrentAnimation`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rotate`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `singletap`, `stopAnimation`, `swipe`, `toImage`, `tooltip`, `touchEnabled`, `touchFeedback`, `touchFeedbackColor`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `transitionName`, `translationX`, `translationY`, `translationZ`, `verticalMotionEffect`, `viewShadowColor`, `viewShadowOffset`, `viewShadowRadius` --- - This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1. - Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.