Skip to content

TopBarMenu Overview

The TopBarMenu serves as a customizable menu builder for Material3 App Bars. It generates adaptive menu buttons through a metadata-driven configuration pattern.

Setting Up Top App Bar with TopBarMenu

API Signature

@Composable
fun RowScope.TopBarMenu(
    limitWidthRatio: Float = 0.3f,       // Maximum width ratio (0-1) the menu block can occupy relative to the top bar width
    moreBtnImg: ImageVector = Icons.Filled.MoreVert, // Icon appears when menu items exceed the available space.
    colors: TopBarMenuColors = TopBarMenuDefaults.colors(), // Color customization
    modifies: TopBarMenuModifies = TopBarMenuDefaults.modifies(), // Style modifiers
    actions: Array<ActionMeta> = arrayOf(),          // Array defining individual menu buttons
    scrollState: ScrollState = rememberScrollState() // Scroll state for overflow menu
)

Integration Example

val actions = remember { mutableStateOf(arrayOf(
    ActionMeta(text = "Refresh", image = Icons.Default.Refresh),
    ActionMeta(text = "Settings", image = Icons.Default.Settings)
)) }

Scaffold(
    topBar = {
        TopAppBar(
            modifier = Modifier.shadow(2.dp),
            title = { /* Title content */ },
            navigationIcon = { /* Navigation button */ },
            actions = {
                TopBarMenu(
                    limitWidthRatio = 0.4f,
                    actions = actions.value
                )
            }
        )
    }
) {
    /* Page content */
}

Material 3 Top App Bars use slot APIs for customization. As a result, TopBarMenu operates within a RowScope. This setup may cause menu items to overlap with the title if they're not properly constrained.

Key width control mechanisms:

  1. Manual Control
    Use limitWidthRatio to explicitly restrict the menu block width.

  2. Automatic Control
    Use AutoTopBarMenu for intelligent width calculation. It will automatically adjust the menu block width based on the given navigation block and the title block:

@Composable
fun RowScope.AutoTopBarMenu(
    navigationBlock: @Composable () -> Unit,  // Measures navigation button width
    titleBlock: @Composable () -> Unit,      // Measures title section width
    moreBtnImg: ImageVector = Icons.Filled.MoreVert,
    actions: Array<ActionMeta> = arrayOf(),
    colors: TopBarMenuColors = TopBarMenuDefaults.colors(),
    modifies: TopBarMenuModifies = TopBarMenuDefaults.modifies(),
    scrollState: ScrollState = rememberScrollState()
)

AutoTopBarMenu automatically prevents overlap by performing the following actions:

  • It dynamically measures the available space.
  • It converts excess items into an overflow menu.
  • It preserves the interactive state for all actions.
Last update: August 19, 2025