Options
The options of tabs.
Options
Every key, with the platforms it works on. A dashed platform means the key does nothing there.
31 options shown
The tab bar of the tabs the screen is in, while the screen shows.
Whether the bar shows. A screen on top decides: one with visible: false hides the bar while it is on top, and every screen pushed over it has to say false too, or the bar comes back. mergeOptions applies at once. A hidden bar means the screens draw under it, and the custom row hides with it.
Whether a change of visible animates. On iOS the first application never animates. On Android, false on the screen that appears turns off the bar's animation during a push, pop or stack root change.
How the content changes when another tab is selected on screen, by a press, by back or from code. 'platform' does what the platform does: on Android the tab that goes fades out and the new one fades in and grows (Material's fade through, 300 ms), on iOS the content changes at once. 'none' changes it at once on both platforms. The appear events of a switch and ANN.BottomTabSelected come at its end, so with 'none' right away. The tab that is selected decides: the value of the screen it shows, over its own, the tabs' and the default options. A mergeOptions applies from the next switch. Off screen the content always changes at once.
The tab to select, as an index from 0. It selects once, when the options arrive, at creation (the first tab to show) or in mergeOptions; it is not kept. An index out of range selects nothing (or the first tab at creation) and logs a warning. It sends no press or select events. Without it, the first tab shows. currentTabId wins when both are set.
The tab to select, by id. It matches a tab, or any screen or layout inside it. It works once, like currentTabIndex, and wins over it. An unknown id selects the first tab at creation and nothing in mergeOptions.
The identifier of the bar for end-to-end tests: the accessibility identifier on iOS, the tag and the resource name of the navigation view on Android.
The accessibility label of the bar, which VoiceOver reads. It does nothing on Android.
The test identifier of the "More" button, which the system shows for more tabs than fit. The system draws the list behind it.
Whether the screens of the tabs draw under the bar. On iOS 26 it is on by default (glass), on iOS before 26 and on Android it is off. On iOS a translucent or hidden bar also counts as drawn under. On Android it sets the bottom padding of the screens to 0, while their safe area still counts a shown bar; it fits well with layoutStyle: 'compact'. It applies when a screen appears and in mergeOptions.
The background color of the bar; null gives the default one. On Android the default is the surface container color (colorSurfaceContainer) of the Material 3 theme. Before iOS 26, and in the compatibility mode (UIDesignRequiresCompatibility in Info.plist: iOS 26, and iOS 27 only for an app built with an SDK before iOS 27), the bar is opaque with the color, or system opaque without it, and a transparent color makes it transparent. On iOS 26 and later with glass the color is ignored with one warning, since the system has no color for glass, while a transparent color gives a transparent bar. The theme color bar is its default option.
When the screens of the tabs are created: 'together' creates and draws every tab at the start, and the tabs are ready when all of them are; 'afterInitialTab' creates the selected tab first and the others right after it; 'onSwitchToTab' creates a tab the first time it is selected. The screens of tabs not yet selected get no appear events in any mode. On iOS a text input's autoFocus in a tab drawn before it is selected does nothing: focus it in useScreenAppear. It applies when the tabs are created; mergeOptions does not change it.
The blur style of a translucent bar before iOS 26: 'default' or 'black'. It needs translucent: true, and applies only when set. On iOS 26 the system decides.
The width of the bar. 'stretch' fills the width; 'compact' makes a floating bar of 80 dp for each tab, centered above the navigation bar, and 'stretch' after 'compact' brings the full width back.
The corner radius of the bar's container, in dp. Without it, the container is not clipped and its outline follows the background. It works best with layoutStyle: 'compact'.
The distance from the bottom of the screen to the bar, in dp, for a floating bar. The screens' bottom padding counts it. With layoutStyle: 'compact' the height of the navigation bar is added. It works best with layoutStyle: 'compact' and drawBehind.
Whether the bar is translucent, with the system blur. It applies before iOS 26, where the screens then draw under the bar; on iOS 26 (glass) it does nothing. Android has no blur, so it does nothing there.
Whether the hairline at the top of the bar is removed, by clipping the bar's view to its bounds. The glass bar of iOS 26 has no line, and the clip can cut the shadow of its capsule. Android has no such line; its border is borderColor and borderWidth.
The labels under the icons: 'alwaysShow' shows all, 'showWhenActive' and 'showWhenActiveForce' show the label of the selected tab only, 'alwaysHide' shows none. On iOS there are two states, show and hide: 'alwaysHide' leaves empty titles and centers the icons (and the "More" list and the iPad top bar show icons only), and the other values show the titles. On Android, without it the Material automatic mode applies: all labels up to three tabs, the selected one from four, and all labels when no tab has an icon. mergeOptions changes it on both platforms.
The elevation of the bar's container, in dp. Its shadow shows even without cornerRadius.
Whether the bar hides when the content of the screen scrolls down and comes back on a scroll up. The bar slides down together with what lies under it, in 200 ms, and the screen then draws under it, so the screen's safe area does not keep the bottom without layout.safeAreaEdges. It follows a new screen after a push, and turning it off brings a hidden bar back. The scrolling view must be the root of the screen and have nestedScrollEnabled. iOS ignores it; minimizeBehavior on iOS 26 is the nearest thing.
The color of the border at the top of the bar. Before iOS 26 it draws a line in the shadow image of every tab (black if only borderWidth is set); on iOS 26 with glass it does not show. On Android it shows a line, dark gray by default, and the theme color border is its default option.
The thickness of the border at the top of the bar: points on iOS (0.1 when only the color is set), dp on Android (a thin line when only the color is set). It works with borderColor.
The shadow of the bar.
The custom row, a row of component cells drawn in place of the bar. It needs bottomTab.component on every tab.
(iOS 18+) Lets the user customize the tabs on an iPad with sidebar: 'sidebar': Edit in the sidebar reorders, hides and adds the tabs. The system saves the arrangement under this id and the tab ids, so the id must be unique in the app and the tabs need stable ids. Without it, or empty, the tabs keep the layout order and are not customizable. It reads at creation only.
(iOS 26+) When the bar shrinks to the selected tab as content scrolls: 'automatic' leaves it to the system (on iPhone 26.5 it does not shrink), 'never', 'onScrollDown', 'onScrollUp'. With a custom row it stays 'never' with a warning. It applies at creation and in mergeOptions.
(iOS 26+) The accessory above the tab bar.
The tab of a screen that is a tab of a tab bar (or the first screen of a stack that is one).