New Compose Multiplatform components arrived on Composables UICheck it out →

TopAppBar

Top app bars display information and actions at the top of a screen.

This small TopAppBar has slots for a title, navigation icon, and actions.

Small top app bar
image

Last updated:

Installation

dependencies {
   implementation("androidx.compose.material3:material3:1.3.0-beta03")
}

Overloads

@Composable
@ExperimentalMaterial3Api
@Deprecated(
    message = "Deprecated in favor of TopAppBar with expandedHeight parameter",
    level = DeprecationLevel.HIDDEN

fun TopAppBar(
    title: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    navigationIcon: @Composable () -> Unit = {},
    actions: @Composable RowScope.() -> Unit = {},
    windowInsets: WindowInsets = TopAppBarDefaults.windowInsets,
    colors: TopAppBarColors = TopAppBarDefaults.topAppBarColors(),
    scrollBehavior: TopAppBarScrollBehavior? = null
)

Parameters

namedescription
titlethe title to be displayed in the top app bar
modifierthe [Modifier] to be applied to this top app bar
navigationIconthe navigation icon displayed at the start of the top app bar. This should typically be an [IconButton] or [IconToggleButton].
actionsthe actions displayed at the end of the top app bar. This should typically be [IconButton]s. The default layout here is a [Row], so icons inside will be placed horizontally.
windowInsetsa window insets that app bar will respect.
colors[TopAppBarColors] that will be used to resolve the colors used for this top app bar in different states. See [TopAppBarDefaults.topAppBarColors].
scrollBehaviora [TopAppBarScrollBehavior] which holds various offset values that will be applied by this top app bar to set up its height and colors. A scroll behavior is designed to work in conjunction with a scrolled content to change the top app bar appearance as the content scrolls. See [TopAppBarScrollBehavior.nestedScrollConnection].
@Composable
@ExperimentalMaterial3Api
fun TopAppBar(
    title: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    navigationIcon: @Composable () -> Unit = {},
    actions: @Composable RowScope.() -> Unit = {},
    expandedHeight: Dp = TopAppBarDefaults.TopAppBarExpandedHeight,
    windowInsets: WindowInsets = TopAppBarDefaults.windowInsets,
    colors: TopAppBarColors = TopAppBarDefaults.topAppBarColors(),
    scrollBehavior: TopAppBarScrollBehavior? = null
)

Parameters

namedescription
titlethe title to be displayed in the top app bar
modifierthe [Modifier] to be applied to this top app bar
navigationIconthe navigation icon displayed at the start of the top app bar. This should typically be an [IconButton] or [IconToggleButton].
actionsthe actions displayed at the end of the top app bar. This should typically be [IconButton]s. The default layout here is a [Row], so icons inside will be placed horizontally.
expandedHeightthis app bar's height. When a specified [scrollBehavior] causes the app bar to collapse or expand, this value will represent the maximum height that the bar will be allowed to expand. This value must be specified and finite, otherwise it will be ignored and replaced with [TopAppBarDefaults.TopAppBarExpandedHeight].
windowInsetsa window insets that app bar will respect.
colors[TopAppBarColors] that will be used to resolve the colors used for this top app bar in different states. See [TopAppBarDefaults.topAppBarColors].
scrollBehaviora [TopAppBarScrollBehavior] which holds various offset values that will be applied by this top app bar to set up its height and colors. A scroll behavior is designed to work in conjunction with a scrolled content to change the top app bar appearance as the content scrolls. See [TopAppBarScrollBehavior.nestedScrollConnection].

Code Examples

SimpleTopAppBar

@Composable
@Sampled
@Preview
@OptIn(ExperimentalMaterial3Api::class
fun SimpleTopAppBar() {
    Scaffold(
        topBar = {
            TopAppBar(
                title = {
                    Text("Simple TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis)
                },
                navigationIcon = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(
                            imageVector = Icons.Filled.Menu,
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(
                            imageVector = Icons.Filled.Favorite,
                            contentDescription = "Localized description"
                        )
                    }
                }
            )
        },
        content = { innerPadding ->
            LazyColumn(
                contentPadding = innerPadding,
                verticalArrangement = Arrangement.spacedBy(8.dp)
            ) {
                val list = (0..75).map { it.toString() }
                items(count = list.size) {
                    Text(
                        text = list[it],
                        style = MaterialTheme.typography.bodyLarge,
                        modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp)
                    )
                }
            }
        }
    )
}

PinnedTopAppBar

@Composable
@Sampled
@Preview
@OptIn(ExperimentalMaterial3Api::class
fun PinnedTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            TopAppBar(
                title = { Text("TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                navigationIcon = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(
                            imageVector = Icons.Filled.Menu,
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    // RowScope here, so these icons will be placed horizontally
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(
                            imageVector = Icons.Filled.Favorite,
                            contentDescription = "Localized description"
                        )
                    }
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(
                            imageVector = Icons.Filled.Favorite,
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior
            )
        },
        content = { innerPadding ->
            LazyColumn(
                contentPadding = innerPadding,
                verticalArrangement = Arrangement.spacedBy(8.dp)
            ) {
                val list = (0..75).map { it.toString() }
                items(count = list.size) {
                    Text(
                        text = list[it],
                        style = MaterialTheme.typography.bodyLarge,
                        modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp)
                    )
                }
            }
        }
    )
}

EnterAlwaysTopAppBar

@Composable
@Sampled
@Preview
@OptIn(ExperimentalMaterial3Api::class
fun EnterAlwaysTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            TopAppBar(
                title = { Text("TopAppBar", maxLines = 1, overflow = TextOverflow.Ellipsis) },
                navigationIcon = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(
                            imageVector = Icons.Filled.Menu,
                            contentDescription = "Localized description"
                        )
                    }
                },
                actions = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(
                            imageVector = Icons.Filled.Favorite,
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior
            )
        },
        content = { innerPadding ->
            LazyColumn(
                contentPadding = innerPadding,
                verticalArrangement = Arrangement.spacedBy(8.dp)
            ) {
                val list = (0..75).map { it.toString() }
                items(count = list.size) {
                    Text(
                        text = list[it],
                        style = MaterialTheme.typography.bodyLarge,
                        modifier = Modifier.fillMaxWidth().padding(horizontal = 16.dp)
                    )
                }
            }
        }
    )
}