ShortNavigationBar

Component in Material 3 Compose

Material Design short navigation bar.

Short navigation bars offer a persistent and convenient way to switch between primary destinations in an app.

The recommended configuration of the [ShortNavigationBar] depends on the width size of the screen it's being displayed at:

• In small screens, the [ShortNavigationBar] should contain three to five [ShortNavigationBarItem]s, each representing a singular destination, and its [arrangement] should be [ShortNavigationBarArrangement.EqualWeight], so that the navigation items are equally distributed on the bar.
• In medium screens, [ShortNavigationBar] should contain three to six [ShortNavigationBarItem]s, each representing a singular destination, and its [arrangement] should be [ShortNavigationBarArrangement.Centered], so that the navigation items are distributed grouped on the center of the bar.

A simple example of the first configuration looks like this:

@sample androidx.compose.material3.samples.ShortNavigationBarSample

And of the second configuration:

@sample androidx.compose.material3.samples.ShortNavigationBarWithHorizontalItemsSample

See [ShortNavigationBarItem] for configurations specific to each item, and not the overall [ShortNavigationBar] component.

Last updated: 2024-10-22 13:47

Installation

dependencies {
   implementation("androidx.compose.material3:material3:1.4.0-alpha02")
}

Overloads

@ExperimentalMaterial3ExpressiveApi
@Composable
fun ShortNavigationBar(
    modifier: Modifier = Modifier,
    containerColor: Color = ShortNavigationBarDefaults.containerColor,
    contentColor: Color = ShortNavigationBarDefaults.contentColor,
    windowInsets: WindowInsets = ShortNavigationBarDefaults.windowInsets,
    arrangement: ShortNavigationBarArrangement = ShortNavigationBarDefaults.arrangement,
    content: @Composable () -> Unit
)

Parameters

name	description
modifier	the [Modifier] to be applied to this navigation bar
containerColor	the color used for the background of this navigation bar. Use [Color.Transparent] to have no color
contentColor	the color for content inside this navigation bar.
windowInsets	a window insets of the navigation bar
arrangement	the [ShortNavigationBarArrangement] of this navigation bar
content	the content of this navigation bar, typically [ShortNavigationBarItem]s

Code Examples

ShortNavigationBarSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun ShortNavigationBarSample() {
    var selectedItem by remember { mutableIntStateOf(0) }
    val items = listOf("Songs", "Artists", "Playlists")
    val selectedIcons = listOf(Icons.Filled.Home, Icons.Filled.Favorite, Icons.Filled.Star)
    val unselectedIcons =
        listOf(Icons.Outlined.Home, Icons.Outlined.FavoriteBorder, Icons.Outlined.StarBorder)

    ShortNavigationBar {
        items.forEachIndexed { index, item ->
            ShortNavigationBarItem(
                icon = {
                    Icon(
                        if (selectedItem == index) selectedIcons[index] else unselectedIcons[index],
                        contentDescription = null
                    )
                },
                label = { Text(item) },
                selected = selectedItem == index,
                onClick = { selectedItem = index }
            )
        }
    }
}

ShortNavigationBarWithHorizontalItemsSample

@OptIn(ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun ShortNavigationBarWithHorizontalItemsSample() {
    var selectedItem by remember { mutableIntStateOf(0) }
    val items = listOf("Songs", "Artists", "Playlists")
    val selectedIcons = listOf(Icons.Filled.Home, Icons.Filled.Favorite, Icons.Filled.Star)
    val unselectedIcons =
        listOf(Icons.Outlined.Home, Icons.Outlined.FavoriteBorder, Icons.Outlined.StarBorder)

    Column {
        Text(
            "Note: this is configuration is better displayed in medium screen sizes.",
            Modifier.padding(16.dp)
        )

        Spacer(Modifier.height(32.dp))

        ShortNavigationBar(arrangement = ShortNavigationBarArrangement.Centered) {
            items.forEachIndexed { index, item ->
                ShortNavigationBarItem(
                    iconPosition = NavigationItemIconPosition.Start,
                    icon = {
                        Icon(
                            if (selectedItem == index) selectedIcons[index]
                            else unselectedIcons[index],
                            contentDescription = null
                        )
                    },
                    label = { Text(item) },
                    selected = selectedItem == index,
                    onClick = { selectedItem = index }
                )
            }
        }
    }
}