# Navigation rail

> A vertical rail that collapses to icons or expands to full labels.

- Category: Navigation
- API status: Expressive
- Compose APIs: `WideNavigationRail`, `WideNavigationRailItem`, `rememberWideNavigationRailState`, `ModalWideNavigationRail`
- Interactive page: https://m3e.ljzapps.app/#components/navigation-rail

## When to use

The wide navigation rail replaces the baseline rail and the standard drawer on medium and larger windows. One component covers both: collapsed it shows icons with small labels, expanded it shows icons beside full labels.

Toggle it from a menu button in the header. Pass railExpanded to every item so they lay out for the current state.

## Examples

### Collapsible rail

Use the menu button to expand and collapse.

```kotlin
val state = rememberWideNavigationRailState()
val scope = rememberCoroutineScope()
var selected by rememberSaveable { mutableIntStateOf(0) }
val expanded = state.targetValue == WideNavigationRailValue.Expanded

Box(Modifier.fillMaxWidth().height(380.dp)) {
    WideNavigationRail(
        state = state,
        header = {
            IconButton(
                modifier = Modifier.padding(start = 24.dp),
                onClick = { scope.launch { state.toggle() } },
            ) {
                Icon(
                    imageVector = if (expanded) Icons.Rounded.Close else Icons.Rounded.Menu,
                    contentDescription = if (expanded) "Collapse rail" else "Expand rail",
                )
            }
        },
    ) {
        NavDestinations.take(4).forEachIndexed { index, (icon, label) ->
            WideNavigationRailItem(
                selected = selected == index,
                onClick = { selected = index },
                icon = { Icon(icon, contentDescription = null) },
                label = { Text(label) },
                railExpanded = expanded,
            )
        }
    }
}
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `state` | `WideNavigationRailState` | `rememberWideNavigationRailState()` | Holds Collapsed or Expanded and animates between them. |
| `header` | `@Composable (() -> Unit)?` | `null` | Slot for a menu button or a FAB. |
| `railExpanded` | `Boolean` |  | Item parameter. Must match the rail state. |
| `arrangement` | `Arrangement.Vertical` | `WideNavigationRailDefaults.arrangement` | Vertical placement of the items. |

## Guidelines

Do:
- Show the rail from the medium size class.
- Offer the main FAB in the header.

Don't:
- Do not combine a rail with a bottom bar.
- Do not use more than seven destinations.

## Accessibility

- The toggle button needs a state aware description such as Expand rail.
- The rail is a navigation landmark. Keep the item order stable between states.

## Related components

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