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.

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.