Top app bar

Shows the screen title and the most important actions at the top of a screen.

Category: Navigation
API status: Expressive
Compose APIs: TopAppBar, CenterAlignedTopAppBar, MediumTopAppBar, LargeTopAppBar, MediumFlexibleTopAppBar, LargeFlexibleTopAppBar, TopAppBarDefaults
Interactive page: https://m3e.ljzapps.app/#components/top-app-bar

When to use

Small and center aligned bars suit simple screens. Medium and large bars show a big title that collapses into a small bar while content scrolls. The flexible variants add an optional subtitle and a title alignment option.

Connect the bar to the scrolling content with a scroll behavior and nestedScroll. Pinned keeps the bar visible, enter always shows it again as soon as the user scrolls up and exit until collapsed collapses the large title.

Playground

The interactive page has a playground with live property controls for this component and generated code.

Examples

Collapsing large bar

Scroll the list.

val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()

Scaffold(
    modifier = Modifier.fillMaxWidth().height(320.dp).nestedScroll(scrollBehavior.nestedScrollConnection),
    topBar = {
        LargeTopAppBar(
            title = { Text("Library") },
            navigationIcon = {
                IconButton(onClick = {}) { Icon(Icons.Rounded.ArrowBack, contentDescription = "Back") }
            },
            scrollBehavior = scrollBehavior,
        )
    },
) { padding ->
    LazyColumn(contentPadding = padding) {
        items((1..30).toList()) { index -> ListItem(headlineContent = { Text("Album $index") }) }
    }
}

Parameters

Name	Type	Default	Description
`title`	`@Composable () -> Unit`		The screen title.
`subtitle`	`@Composable (() -> Unit)?`	`null`	Flexible variants only.
`navigationIcon`	`@Composable () -> Unit`	`{}`	Usually a back or menu button.
`actions`	`@Composable RowScope.() -> Unit`	`{}`	Up to three icon buttons, extra ones go to an overflow menu.
`scrollBehavior`	`TopAppBarScrollBehavior?`	`null`	Use together with Modifier.nestedScroll.

Guidelines

Do:

Keep titles short.
Limit visible actions to three.

Don't:

Do not hide the back button on detail screens.
Do not combine a large bar with a tab row above it.

Accessibility

Mark the title as a heading so screen reader users can jump to it.
Every action needs a content description. Overflow actions are menu items with text.