# ModalWideNavigationRail

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/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)( modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, state: https://developer.android.com/reference/kotlin/androidx/compose/material3/WideNavigationRailState, hideOnCollapse: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, collapsedShape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape, expandedShape: 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)?, expandedHeaderTopPadding: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp, 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, expandedProperties: https://developer.android.com/reference/kotlin/androidx/compose/material3/ModalWideNavigationRailProperties, 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 modal wide navigation rail. | Cmn |

## Functions

### ModalWideNavigationRail

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:ModalWideNavigationRail)

```
@Composable
fun ModalWideNavigationRail(
    modifier: Modifier = Modifier,
    state: WideNavigationRailState = rememberWideNavigationRailState(),
    hideOnCollapse: Boolean = false,
    collapsedShape: Shape = WideNavigationRailDefaults.modalCollapsedShape,
    expandedShape: Shape = WideNavigationRailDefaults.modalExpandedShape,
    colors: WideNavigationRailColors = WideNavigationRailDefaults.colors(),
    header: (@Composable () -> Unit)? = null,
    expandedHeaderTopPadding: Dp = 0.dp,
    windowInsets: WindowInsets = WideNavigationRailDefaults.windowInsets,
    arrangement: Arrangement.Vertical = WideNavigationRailDefaults.arrangement,
    expandedProperties: ModalWideNavigationRailProperties = WideNavigationRailDefaults.ModalExpandedProperties,
    contentPadding: PaddingValues = WideNavigationRailDefaults.ContentPadding,
    content: @Composable () -> Unit
): Unit
```

Material design modal wide navigation rail.

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

The modal 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/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)` when collapsed behaves like a collapsed `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)`. When expanded, the modal wide navigation rail blocks interaction with the rest of an app's content with a scrim. It is elevated above the app's UI and doesn't affect the screen's layout grid. That can be achieved 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.ModalWideNavigationRail
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()) {
    ModalWideNavigationRail(
        state = state,
        // Note: the value of expandedHeaderTopPadding depends on the layout of your screen in
        // order to achieve the best alignment.
        expandedHeaderTopPadding = 64.dp,
        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 = {
                    Icon(
                        if (selectedItem == index) selectedIcons[index]
                        else unselectedIcons[index],
                        contentDescription = item,
                    )
                },
                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 = "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 dismissible `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)`, that enters from offscreen instead of expanding from the collapsed rail, set `https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#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)` to true. That can be achieved like so:

```kotlin
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
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.Button
import androidx.compose.material3.Icon
import androidx.compose.material3.ModalWideNavigationRail
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.rememberWideNavigationRailState
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.style.TextAlign
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()

Row(Modifier.fillMaxSize()) {
    ModalWideNavigationRail(state = state, hideOnCollapse = true) {
        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
                    scope.launch { state.collapse() }
                },
            )
        }
    }

    Column(Modifier.fillMaxWidth(), horizontalAlignment = Alignment.CenterHorizontally) {
        val currentPage = items.get(selectedItem)
        Button(onClick = { scope.launch { state.expand() } }, Modifier.padding(32.dp)) {
            Text(text = "$currentPage Page\nOpen modal rail", textAlign = TextAlign.Center)
        }
    }
}
```

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/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)` 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 |
| `hideOnCollapse: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = false` | whether this wide navigation rail should slide offscreen when it collapses and be hidden, or stay on screen as a collapsed wide navigation rail (default) |
| `collapsedShape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape = WideNavigationRailDefaults.modalCollapsedShape` | the shape of this wide navigation rail's container when it's collapsed |
| `expandedShape: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Shape = WideNavigationRailDefaults.modalExpandedShape` | the shape of this wide navigation rail's container when it's expanded |
| `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 |
| `expandedHeaderTopPadding: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp = 0.dp` | the padding to be applied to the top of the rail. It's usually needed in order to align the content of the rail between the collapsed and expanded animation |
| `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 |
| `expandedProperties: https://developer.android.com/reference/kotlin/androidx/compose/material3/ModalWideNavigationRailProperties = WideNavigationRailDefaults.ModalExpandedProperties` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/ModalWideNavigationRailProperties` for further customization of the expanded modal wide navigation rail's window behavior |
| `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 modal wide navigation rail, usually `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 |