Top App Bar
Bar across the top of a screen holding its title, a navigation control, and a few actions. Material's top app bars read those in order as one group, but none marks the title as a heading, so the heading, the navigation control's name, and keeping the bar off the content beneath are the caller's.
Selection
The criteria an agent checks before retrieving this component.
Use when
- Use when a screen shows its title at the top, with a back or menu control before it and a few actions after it (e.g., "Inbox" with "Search" and "More options").
Try a different component when
- Do not use when the bar moves between the app's top-level destinations (use
navigation-bar.basicortabs.basic). - Do not use when the screen's actions sit along the bottom (use
bottom-app-bar.basic). - Do not use when the title belongs to a dialog or a sheet (use
dialog.alertorbottom-sheet.modal).
Must Haves
Non-negotiable structure. Every generated instance must satisfy these rules.
- The bar reads its navigation control, the screen's title, and its actions, in that order, as one group. Material's
TopAppBar,CenterAlignedTopAppBar,MediumTopAppBar, andLargeTopAppBarare the reference implementation: each marks itself a traversal group and lays out the navigation icon, the title, and the actions in that order (global.native-first,global.traversal-order). - Mark the title with
Modifier.semantics { heading() }. None of Material's top app bars marks it, and it is the heading a TalkBack user reaches first on the screen (global.headings). - Make the title the screen's name, as visible text (
global.screen-announcement). - Name the navigation control on its
Iconfor what it does: "Navigate up" for an arrow that returns to the previous level, the label Android uses for that control, or "Open navigation menu" for a menu icon that opens a drawer (navigation-drawer.modal). UseIcons.AutoMirrored.Filled.ArrowBackso the arrow points the right way in right-to-left layouts (global.icon). - Name each action on its
Icon, asbutton.basicdescribes. Move actions beyond the first few into an overflow menu named "More options" (menu.basic), and build an action that turns something on or off asbutton.toggledescribes. - Apply the
Scaffold'sinnerPaddingto the content asModifier.padding, so the scrolling area starts below the bar. Content scrolled beneath a bar can hold a focused item the bar then covers (global.focus-not-obscured). - 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 name the navigation control for its shape ("Arrow", "Hamburger"). The user needs what it does.
- Do not mark anything else in the bar as a heading. The title is the bar's only heading.
- Do not build a two-row bar by stacking a small title over a large one.
MediumTopAppBarandLargeTopAppBarhide one of their two titles from accessibility services while they collapse; a hand-built pair is read twice. - Do not show the screen's name only as an image with no name. When the bar shows a logo in place of text, the logo carries the name.
Customizable
Alternatives and options that give the AI agent some room to move.
- Any of the four bars may be used; they share the same semantics and differ in size and title alignment.
- A logo may stand in for the title text, as an
Imagewith acontentDescriptionnaming the screen or the app, marked withheading(). - A bar that collapses or hides as the content scrolls takes a
TopAppBarScrollBehavior, which Material still marks experimental and which needs@OptIn(ExperimentalMaterial3Api::class). Nothing else in this pattern changes.
Golden Pattern
The tested reference implementation. Agents start from this shape and adapt to the developer’s codebase and context.
@Composable
fun TopAppBarExamples(onNavigateUp: () -> Unit) {
Scaffold(
topBar = {
TopAppBar(
title = {
Text("Inbox", modifier = Modifier.semantics { heading() })
},
navigationIcon = {
IconButton(onClick = onNavigateUp) {
Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "Navigate up")
}
},
actions = {
IconButton(onClick = { /* search */ }) {
Icon(Icons.Filled.Search, contentDescription = "Search")
}
IconButton(onClick = { /* open the menu, as menu.basic describes */ }) {
Icon(Icons.Filled.MoreVert, contentDescription = "More options")
}
}
)
}
) { innerPadding ->
LazyColumn(modifier = Modifier.padding(innerPadding)) {
/* messages */
}
}
}