Navigation Bar
Bar of three to five top-level destinations along the bottom of the screen. Each item reports Role.Tab, its selected state, and its position, and Material removes the icon's semantics whenever the label shows, which takes any badge with it.
Selection
The criteria an agent checks before retrieving this component.
Use when
- Use when the app has three to five top-level destinations the user moves between from anywhere (e.g., "Home", "Search", "Library", "Inbox").
- Use when the destinations are peers and none is a sub-view of another.
Try a different component when
- Do not use when the options switch between views inside one screen (use
tabs.basic). - Do not use when the layout is wide enough for a side rail (use
navigation-rail.basic). - Do not use when the bar holds actions for the current screen rather than destinations (use
bottom-app-bar.basic). - Do not use when there are more than five destinations (use
navigation-drawer.modal).
Must Haves
Non-negotiable structure. Every generated instance must satisfy these rules.
- Each item reports
Role.Tab, its selected state, and a click action, and the bar reports position within the set. Material'sNavigationBarandNavigationBarItemare the reference implementation of that contract, throughselectable(role = Role.Tab)on each item andselectableGroup()on the bar; a design system's own bar satisfies it by forwarding to the same semantics, and a hand-assembled one satisfies none of it by default (global.native-first). - Give each item a visible
label. - Give each item's
IconacontentDescriptionmatching its label. Material discards it whenever the label is showing, and it is the item's only name when the label is hidden (alwaysShowLabel = falseon an unselected item) or absent. - Put a badge's meaning in the item's name, with
Modifier.semantics { contentDescription = "..." }on theNavigationBarItem(e.g., "Inbox, 3 new messages"). ABadgedBoxin the icon slot is cleared along with the icon whenever the label shows. - Mark the selected item from the current destination, so the selected state TalkBack reports matches the screen the user is on.
- Give each destination a visible title when it opens, so moving between them is announced (
global.screen-announcement). - If a destination 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 the icon
contentDescription = nullon the assumption that the label always names the item. SetalwaysShowLabel = falseand every unselected item loses its name. - Do not rely on a
BadgedBoxto announce a count or a dot. The item has to carry it. - Do not build the bar from
RowandModifier.clickableitems. They announce as buttons, report no selected state, and lose their position in the set. - Do not put actions such as "Compose" or "Share" in the bar. Its items report
Role.Tab, which tells the user each one is a place. - Do not convey the selected item by color alone. Material draws an indicator shape behind the selected item's icon, which carries it; a restyled bar that changes only the tint does not (
global.use-of-color).
Customizable
Alternatives and options that give the AI agent some room to move.
- Labels may be shown on every item (
alwaysShowLabel = true, the default) or on the selected item only. Hiding them is a visual choice that moves the naming duty to the icons. NavigationBarItemDefaults.colorsand the container color may follow the brand, provided the selected state stays distinguishable without color.- A badge may show a count or a dot. A dot's meaning goes in the item's name as words (e.g., "Inbox, new messages").
Golden Pattern
The tested reference implementation. Agents start from this shape and adapt to the developer’s codebase and context.
@Composable
fun NavigationBarExamples(current: Destination, unread: Int, onNavigate: (Destination) -> Unit) {
NavigationBar {
Destination.entries.forEach { destination ->
NavigationBarItem(
selected = destination == current,
onClick = { onNavigate(destination) },
label = { Text(destination.label) },
icon = {
if (destination == Destination.Inbox && unread > 0) {
BadgedBox(badge = { Badge { Text("$unread") } }) {
Icon(destination.icon, contentDescription = destination.label)
}
} else {
Icon(destination.icon, contentDescription = destination.label)
}
},
modifier = if (destination == Destination.Inbox && unread > 0) {
Modifier.semantics { contentDescription = "Inbox, $unread new messages" }
} else {
Modifier
}
)
}
}
}