Navigation bar

Switches between three to five top level destinations on compact windows.

Category: Navigation
API status: Expressive
Compose APIs: ShortNavigationBar, ShortNavigationBarItem, NavigationBar, NavigationBarItem
Interactive page: https://m3e.ljzapps.app/#components/navigation-bar

When to use

The short navigation bar is the Expressive navigation bar. It is shorter than the baseline bar, supports icons beside labels and a centered arrangement for wider windows. The baseline NavigationBar is still available.

Use a bar on compact windows only. From the medium size class on, switch to a navigation rail.

Playground

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

Examples

Short navigation bar

Expressive. Select a destination.

var selected by rememberSaveable { mutableIntStateOf(0) }
val destinations = listOf(
    Icons.Rounded.Home to "Home",
    Icons.Rounded.Search to "Search",
    Icons.Rounded.LibraryMusic to "Library",
)

ShortNavigationBar {
    destinations.forEachIndexed { index, (icon, label) ->
        ShortNavigationBarItem(
            selected = selected == index,
            onClick = { selected = index },
            icon = { Icon(icon, contentDescription = null) },
            label = { Text(label) },
        )
    }
}

Baseline navigation bar

var selected by rememberSaveable { mutableIntStateOf(0) }
val destinations = listOf(
    Icons.Rounded.Home to "Home",
    Icons.Rounded.Search to "Search",
    Icons.Rounded.LibraryMusic to "Library",
)

NavigationBar {
    destinations.forEachIndexed { index, (icon, label) ->
        NavigationBarItem(
            selected = selected == index,
            onClick = { selected = index },
            icon = { Icon(icon, contentDescription = null) },
            label = { Text(label) },
        )
    }
}

Parameters

Name	Type	Default	Description
`arrangement`	`ShortNavigationBarArrangement`	`EqualWeight`	EqualWeight fills the width, Centered groups items in the middle.
`selected`	`Boolean`		Item parameter. Marks the active destination.
`icon / label`	`@Composable`		Item parameters. The label may be null for icon only items.
`iconPosition`	`NavigationItemIconPosition`	`Top`	Top stacks icon above label, Start puts them side by side.

Guidelines

Do:

Use three to five destinations.
Use a badge to signal new content.

Don't:

Do not use for actions. Use buttons.
Do not hide or add destinations at runtime.

Accessibility

Selected items expose the selected state. Do not rely on the indicator color alone.
Always show labels. Icon only bars are hard to understand.
Keep the order of destinations stable.