# WideNavigationRail

Common/AllAndroid/JVM

## Functions summary

|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRail.composable#WideNavigationRail(androidx.compose.ui.Modifier,androidx.compose.material3.WideNavigationRailState,androidx.compose.ui.graphics.Shape,androidx.compose.material3.WideNavigationRailColors,kotlin.Function0,androidx.compose.foundation.layout.WindowInsets,androidx.compose.foundation.layout.Arrangement.Vertical,androidx.compose.foundation.layout.PaddingValues,kotlin.Function0)( modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, state: https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailState, shape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape, colors: https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailColors, header: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, windowInsets: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/WindowInsets, arrangement: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Arrangement.Vertical, contentPadding: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues, content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Material design wide navigation rail. | Cmn |

## Functions

### WideNavigationRail

Cmn Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/WideNavigationRail.kt+function:WideNavigationRail)

```
@Composable
fun WideNavigationRail(
    modifier: Modifier = Modifier,
    state: WideNavigationRailState = rememberWideNavigationRailState(),
    shape: Shape = WideNavigationRailDefaults.shape,
    colors: WideNavigationRailColors = WideNavigationRailDefaults.colors(),
    header: (@Composable () -> Unit)? = null,
    windowInsets: WindowInsets = WideNavigationRailDefaults.windowInsets,
    arrangement: Arrangement.Vertical = WideNavigationRailDefaults.arrangement,
    contentPadding: PaddingValues = WideNavigationRailDefaults.ContentPadding,
    content: @Composable () -> Unit
): Unit
```

Material design wide navigation rail.

Wide navigation rails provide access to primary destinations in apps when using tablet and desktop screens.

![Wide navigation rail collapsed
image](https://developer.android.com/images/reference/androidx/compose/material3/wide-navigation-rail-collapsed.png)

![Wide navigation rail expanded
image](https://developer.android.com/images/reference/androidx/compose/material3/wide-navigation-rail-expanded.png)

The wide navigation rail should be used to display multiple `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailItem.composable#WideNavigationRailItem(kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.material3.NavigationItemIconPosition,androidx.compose.material3.NavigationItemColors,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.foundation.layout.PaddingValues)`s, each representing a singular app destination, and, optionally, a header containing a menu button, a `https://developer.android.com/reference/kotlin/androidx/compose/material3/FloatingActionButton.composable#FloatingActionButton(kotlin.Function0,androidx.compose.ui.Modifier,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.material3.FloatingActionButtonElevation,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Function0)`, and/or a logo. Each destination is typically represented by an icon and a text label.

The `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRail.composable#WideNavigationRail(androidx.compose.ui.Modifier,androidx.compose.material3.WideNavigationRailState,androidx.compose.ui.graphics.Shape,androidx.compose.material3.WideNavigationRailColors,kotlin.Function0,androidx.compose.foundation.layout.WindowInsets,androidx.compose.foundation.layout.Arrangement.Vertical,androidx.compose.foundation.layout.PaddingValues,kotlin.Function0)` is collapsed by default, but it also supports being expanded via a `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailState`. When collapsed, the rail should display three to seven navigation items. A simple example looks like:

```kotlin
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.filled.Home
import androidx.compose.material.icons.filled.Star
import androidx.compose.material.icons.outlined.FavoriteBorder
import androidx.compose.material.icons.outlined.Home
import androidx.compose.material.icons.outlined.StarBorder
import androidx.compose.material3.Icon
import androidx.compose.material3.NavigationRail
import androidx.compose.material3.NavigationRailItem
import androidx.compose.material3.Text
import androidx.compose.material3.WideNavigationRail
import androidx.compose.material3.WideNavigationRailItem
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.saveable.rememberSaveable

var selectedItem by rememberSaveable { mutableIntStateOf(0) }
val items = listOf("Home", "Search", "Settings")
val selectedIcons = listOf(Icons.Filled.Home, Icons.Filled.Favorite, Icons.Filled.Star)
val unselectedIcons =
    listOf(Icons.Outlined.Home, Icons.Outlined.FavoriteBorder, Icons.Outlined.StarBorder)
WideNavigationRail {
    items.forEachIndexed { index, item ->
        WideNavigationRailItem(
            railExpanded = false,
            icon = {
                Icon(
                    if (selectedItem == index) selectedIcons[index] else unselectedIcons[index],
                    contentDescription = null,
                )
            },
            label = { Text(item) },
            selected = selectedItem == index,
            onClick = { selectedItem = index },
        )
    }
}
```

When expanded, the rail should display at least three navigation items. A simple example looks like:

```kotlin
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.filled.Home
import androidx.compose.material.icons.filled.Star
import androidx.compose.material.icons.outlined.FavoriteBorder
import androidx.compose.material.icons.outlined.Home
import androidx.compose.material.icons.outlined.StarBorder
import androidx.compose.material3.Icon
import androidx.compose.material3.NavigationRail
import androidx.compose.material3.NavigationRailItem
import androidx.compose.material3.Text
import androidx.compose.material3.WideNavigationRail
import androidx.compose.material3.WideNavigationRailItem
import androidx.compose.material3.WideNavigationRailValue
import androidx.compose.material3.rememberWideNavigationRailState
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.saveable.rememberSaveable

var selectedItem by rememberSaveable { mutableIntStateOf(0) }
val items = listOf("Home", "Search", "Settings")
val selectedIcons = listOf(Icons.Filled.Home, Icons.Filled.Favorite, Icons.Filled.Star)
val unselectedIcons =
    listOf(Icons.Outlined.Home, Icons.Outlined.FavoriteBorder, Icons.Outlined.StarBorder)
WideNavigationRail(
    state = rememberWideNavigationRailState(initialValue = WideNavigationRailValue.Expanded)
) {
    items.forEachIndexed { index, item ->
        WideNavigationRailItem(
            railExpanded = true,
            icon = {
                Icon(
                    if (selectedItem == index) selectedIcons[index] else unselectedIcons[index],
                    contentDescription = null,
                )
            },
            label = { Text(item) },
            selected = selectedItem == index,
            onClick = { selectedItem = index },
        )
    }
}
```

The `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRail.composable#WideNavigationRail(androidx.compose.ui.Modifier,androidx.compose.material3.WideNavigationRailState,androidx.compose.ui.graphics.Shape,androidx.compose.material3.WideNavigationRailColors,kotlin.Function0,androidx.compose.foundation.layout.WindowInsets,androidx.compose.foundation.layout.Arrangement.Vertical,androidx.compose.foundation.layout.PaddingValues,kotlin.Function0)` also supports automatically animating between the collapsed and expanded values. That can be done like so:

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.MenuOpen
import androidx.compose.material.icons.filled.Favorite
import androidx.compose.material.icons.filled.Home
import androidx.compose.material.icons.filled.Menu
import androidx.compose.material.icons.filled.Star
import androidx.compose.material.icons.outlined.FavoriteBorder
import androidx.compose.material.icons.outlined.Home
import androidx.compose.material.icons.outlined.StarBorder
import androidx.compose.material3.Button
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.NavigationRail
import androidx.compose.material3.NavigationRailItem
import androidx.compose.material3.PlainTooltip
import androidx.compose.material3.Text
import androidx.compose.material3.TooltipAnchorPosition
import androidx.compose.material3.TooltipBox
import androidx.compose.material3.TooltipDefaults
import androidx.compose.material3.WideNavigationRail
import androidx.compose.material3.WideNavigationRailItem
import androidx.compose.material3.WideNavigationRailValue
import androidx.compose.material3.rememberTooltipState
import androidx.compose.material3.rememberWideNavigationRailState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Modifier
import androidx.compose.ui.semantics.LiveRegionMode
import androidx.compose.ui.semantics.liveRegion
import androidx.compose.ui.semantics.paneTitle
import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.semantics.stateDescription
import androidx.compose.ui.unit.dp

var selectedItem by rememberSaveable { mutableIntStateOf(0) }
val items = listOf("Home", "Search", "Settings")
val selectedIcons = listOf(Icons.Filled.Home, Icons.Filled.Favorite, Icons.Filled.Star)
val unselectedIcons =
    listOf(Icons.Outlined.Home, Icons.Outlined.FavoriteBorder, Icons.Outlined.StarBorder)
val state = rememberWideNavigationRailState()
val scope = rememberCoroutineScope()
val headerDescription =
    if (state.targetValue == WideNavigationRailValue.Expanded) {
        "Collapse rail"
    } else {
        "Expand rail"
    }

Row(Modifier.fillMaxWidth()) {
    WideNavigationRail(
        state = state,
        header = {
            // Header icon button should have a tooltip.
            @OptIn(ExperimentalMaterial3Api::class)
            TooltipBox(
                positionProvider =
                    TooltipDefaults.rememberTooltipPositionProvider(
                        TooltipAnchorPosition.Above
                    ),
                tooltip = {
                    PlainTooltip(
                        Modifier.semantics {
                            // TODO(b/496338253): Remove this modifier once bug where tooltip
                            //  text is not announced by a11y screen readers is resolved.
                            liveRegion = LiveRegionMode.Assertive
                            paneTitle = headerDescription
                        }
                    ) {
                        Text(headerDescription)
                    }
                },
                state = rememberTooltipState(),
            ) {
                IconButton(
                    modifier =
                        Modifier.padding(start = 24.dp).semantics {
                            // The button must announce the expanded or collapsed state of the
                            // rail for accessibility.
                            stateDescription =
                                if (state.currentValue == WideNavigationRailValue.Expanded) {
                                    "Expanded"
                                } else {
                                    "Collapsed"
                                }
                        },
                    onClick = {
                        scope.launch {
                            if (state.targetValue == WideNavigationRailValue.Expanded)
                                state.collapse()
                            else state.expand()
                        }
                    },
                ) {
                    if (state.targetValue == WideNavigationRailValue.Expanded) {
                        Icon(Icons.AutoMirrored.Filled.MenuOpen, headerDescription)
                    } else {
                        Icon(Icons.Filled.Menu, headerDescription)
                    }
                }
            }
        },
    ) {
        items.forEachIndexed { index, item ->
            WideNavigationRailItem(
                railExpanded = state.targetValue == WideNavigationRailValue.Expanded,
                icon = {
                    val imageVector =
                        if (selectedItem == index) {
                            selectedIcons[index]
                        } else {
                            unselectedIcons[index]
                        }
                    Icon(imageVector = imageVector, contentDescription = null)
                },
                label = { Text(item) },
                selected = selectedItem == index,
                onClick = { selectedItem = index },
            )
        }
    }

    val textString =
        if (state.currentValue == WideNavigationRailValue.Expanded) {
            "Expanded"
        } else {
            "Collapsed"
        }
    Column {
        Text(modifier = Modifier.padding(16.dp), text = "Is animating: " + state.isAnimating)
        Text(modifier = Modifier.padding(16.dp), text = "The rail is $textString.")
        Text(
            modifier = Modifier.padding(16.dp),
            text =
                "Note: This demo is best shown in portrait mode, as landscape mode" +
                    " may result in a compact height in certain devices. For any" +
                    " compact screen dimensions, use a Navigation Bar instead.",
        )
    }
}
```

For a modal variation of the wide navigation rail, see `https://developer.android.com/reference/kotlin/androidx/compose/material3/ModalWideNavigationRail.composable#ModalWideNavigationRail(androidx.compose.ui.Modifier,androidx.compose.material3.WideNavigationRailState,kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Shape,androidx.compose.material3.WideNavigationRailColors,kotlin.Function0,androidx.compose.ui.unit.Dp,androidx.compose.foundation.layout.WindowInsets,androidx.compose.foundation.layout.Arrangement.Vertical,androidx.compose.material3.ModalWideNavigationRailProperties,androidx.compose.foundation.layout.PaddingValues,kotlin.Function0)`.

Finally, the `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRail.composable#WideNavigationRail(androidx.compose.ui.Modifier,androidx.compose.material3.WideNavigationRailState,androidx.compose.ui.graphics.Shape,androidx.compose.material3.WideNavigationRailColors,kotlin.Function0,androidx.compose.foundation.layout.WindowInsets,androidx.compose.foundation.layout.Arrangement.Vertical,androidx.compose.foundation.layout.PaddingValues,kotlin.Function0)` supports setting an `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Arrangement.Vertical` for the items, with `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Arrangement#Top()` being the default. The header will always be at the top.

See `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailItem.composable#WideNavigationRailItem(kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.material3.NavigationItemIconPosition,androidx.compose.material3.NavigationItemColors,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.foundation.layout.PaddingValues)` for configuration specific to each item, and not the overall `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRail.composable#WideNavigationRail(androidx.compose.ui.Modifier,androidx.compose.material3.WideNavigationRailState,androidx.compose.ui.graphics.Shape,androidx.compose.material3.WideNavigationRailColors,kotlin.Function0,androidx.compose.foundation.layout.WindowInsets,androidx.compose.foundation.layout.Arrangement.Vertical,androidx.compose.foundation.layout.PaddingValues,kotlin.Function0)` component.

| Parameters |
|---|---|
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | the `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` to be applied to this wide navigation rail |
| `state: https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailState = rememberWideNavigationRailState()` | the `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailState` of this wide navigation rail |
| `shape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape = WideNavigationRailDefaults.shape` | defines the shape of this wide navigation rail's container. |
| `colors: https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailColors = WideNavigationRailDefaults.colors()` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailColors` that will be used to resolve the colors used for this wide navigation rail. See `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailDefaults#colors()` |
| `header: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | optional header that may hold a `https://developer.android.com/reference/kotlin/androidx/compose/material3/FloatingActionButton.composable#FloatingActionButton(kotlin.Function0,androidx.compose.ui.Modifier,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.material3.FloatingActionButtonElevation,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Function0)` or a logo |
| `windowInsets: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/WindowInsets = WideNavigationRailDefaults.windowInsets` | a window insets of the wide navigation rail |
| `arrangement: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Arrangement.Vertical = WideNavigationRailDefaults.arrangement` | the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Arrangement.Vertical` of this wide navigation rail for its content. Note that if there's a header present, the items will be arranged on the remaining space below it, except for the center arrangement which considers the entire height of the container |
| `contentPadding: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues = WideNavigationRailDefaults.ContentPadding` | the spacing values to apply internally between the container and the content |
| `content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | the content of this wide navigation rail, typically `https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailItem.composable#WideNavigationRailItem(kotlin.Boolean,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Boolean,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.material3.NavigationItemIconPosition,androidx.compose.material3.NavigationItemColors,androidx.compose.foundation.interaction.MutableInteractionSource,androidx.compose.foundation.layout.PaddingValues)`s |