# 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.

```kotlin
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.

## Related components

- [Bottom app bar](https://m3e.ljzapps.app/docs/components/bottom-app-bar.md)
- [Navigation drawer](https://m3e.ljzapps.app/docs/components/navigation-drawer.md)
- [Search](https://m3e.ljzapps.app/docs/components/search.md)