Tabs
Row of tabs that switches between views of the same screen. Each tab reports Role.Tab, its selected state, and its position, and only the selected tab's content belongs in the tree. Unlike a navigation bar item, a tab keeps its icon's semantics.
Selection
The criteria an agent checks before retrieving this component.
Use when
- Use when one screen offers several views of the same subject and the user switches between them (e.g., "Overview", "Reviews", "Specifications" on a product).
- Use when the views are peers and the user is expected to move between them freely.
Try a different component when
- Do not use when the options are top-level destinations of the app (use
navigation-bar.basic). - Do not use when the control picks a value or filters a list in place (use
segmented-button.basic). - Do not use when the sections are long and meant to be read in sequence (use
accordion.basic).
Must Haves
Non-negotiable structure. Every generated instance must satisfy these rules.
- Each tab reports
Role.Tab, its selected state, and a click action, and the row reports position within the set. Material'sTabinside aPrimaryTabRow,SecondaryTabRow, or scrollable tab row is the reference implementation of that contract, throughselectable(role = Role.Tab)on each tab andselectableGroup()on the row; a design system's own tabs satisfy it by forwarding to the same semantics, and hand-assembled ones satisfy none of it by default (global.native-first). - Give each tab visible text that names its view.
- Give a tab's
IconcontentDescription = nullwhen the tab also has text.Tabkeeps the icon's semantics, so a named icon repeats the tab's name (global.icon). - Give an icon-only tab's
IconacontentDescriptionnaming its view. - Compose only the selected tab's content, so the other views are out of the accessibility tree rather than hidden behind the visible one.
- Keep the selected tab and the visible content in step when the content also responds to swiping, such as a
HorizontalPager. A swipe that changes the view without moving the selection makes TalkBack report the wrong tab as selected. - If a view is unavailable, pass
enabled = falserather than removing the handler, so the control stays in the accessibility tree and reports that it is disabled. - Meets the touch target baseline in
global_rules.md(global.touch-target-size). - Meets the focus states baseline in
global_rules.md(global.focus-states).
Donts
Avoid these accessibility and UX barriers.
- Do not give a tab's icon the same
contentDescriptionas its text. UnlikeNavigationBarItem,Tabdoes not clear it. - Do not build tabs from
RowandModifier.clickableitems. They announce as buttons, report no selected state, and lose their position in the set. - Do not keep the unselected views composed behind the selected one, such as stacked in a
Boxwith the others hidden. Whether TalkBack skips a hidden view depends on how it was hidden; not composing it removes the question. - Do not use tabs to run commands or submit choices. Each tab reports
Role.Tab, which tells the user it shows a view. - Do not convey the selected tab by color alone. The row's indicator line carries it; a restyled row that changes only the text tint does not (
global.use-of-color).
Customizable
Alternatives and options that give the AI agent some room to move.
- Primary or secondary styling and fixed or scrollable layout are visual choices with the same contract. A scrollable row suits more tabs than fit the width.
- Tabs may show text, an icon above text, or an icon alone.
- The views may change on tap only, or also on a horizontal swipe through a
HorizontalPager, provided the selected tab follows the swipe.
Golden Pattern
The tested reference implementation. Agents start from this shape and adapt to the developer’s codebase and context.
@Composable
fun TabsExamples() {
val tabs = listOf("Overview", "Reviews", "Specifications")
var selected by rememberSaveable { mutableIntStateOf(0) }
Column {
PrimaryTabRow(selectedTabIndex = selected) {
tabs.forEachIndexed { index, title ->
Tab(
selected = selected == index,
onClick = { selected = index },
text = { Text(title) }
)
}
}
when (selected) {
0 -> ProductOverview()
1 -> ProductReviews()
2 -> ProductSpecifications()
}
}
}
@Composable
fun SwipeableTabsExample(tabs: List<String>) {
val pagerState = rememberPagerState { tabs.size }
val scope = rememberCoroutineScope()
Column {
PrimaryTabRow(selectedTabIndex = pagerState.currentPage) {
tabs.forEachIndexed { index, title ->
Tab(
selected = pagerState.currentPage == index,
onClick = { scope.launch { pagerState.animateScrollToPage(index) } },
text = { Text(title) },
icon = { Icon(Icons.Outlined.Info, contentDescription = null) }
)
}
}
HorizontalPager(state = pagerState) { page ->
TabPage(tabs[page])
}
}
}