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

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

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

## Related components

- [Navigation rail](https://m3e.ljzapps.app/docs/components/navigation-rail.md)
- [Navigation drawer](https://m3e.ljzapps.app/docs/components/navigation-drawer.md)
- [Badge](https://m3e.ljzapps.app/docs/components/badge.md)