# Modal navigation rail

> A rail that expands over the content as a modal panel and collapses back to icons.

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

## When to use

Use the modal rail on medium windows where a permanent expanded rail would take too much space. Collapsed it behaves like a normal rail. Expanded it overlays the content with a scrim.

With hideOnCollapse the rail disappears completely when collapsed, which suits focused tasks.

## Playground

The interactive page has a playground with live property controls for this component and generated code.

## Examples

### Expand over content

```kotlin
ModalRailDemo()
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `state` | `WideNavigationRailState` | `rememberWideNavigationRailState()` | Collapsed or Expanded. |
| `hideOnCollapse` | `Boolean` | `false` | Remove the rail when collapsed. |
| `header` | `@Composable (() -> Unit)?` | `null` | Menu button or FAB. |
| `railExpanded` | `Boolean` |  | Item parameter, must match the state. |

## Guidelines

Do:
- Collapse after a destination is chosen.
- Keep icon and label consistent.

Don't:
- Do not use it with a bottom bar.
- Do not hide it on medium windows without a menu button.

## Accessibility

- The expanded rail is modal. Focus moves in and returns to the toggle on collapse.

## Related components

- [Navigation rail](https://m3e.ljzapps.app/docs/components/navigation-rail.md)
- [Modal and dismissible drawer](https://m3e.ljzapps.app/docs/components/modal-navigation-drawer.md)
- [Navigation bar](https://m3e.ljzapps.app/docs/components/navigation-bar.md)