# Navigation Rail

Side navigation rail for tablets and foldables that expands into a labelled sidebar. As it widens, the selected pill stretches into a full row and labels appear.

> Composed · Pro · Navigation — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add pro/navigation-rail
```

## Import

```tsx
import { NavigationRail } from "@/components/ui/navigation-rail/navigation-rail";
```

## Variants

- `mail` — Overlay: `npx @lumioui/cli add pro/navigation-rail-mail`
- `media` — Selected labels: `npx @lumioui/cli add pro/navigation-rail-media`
- `sidebar` — Collapsible sidebar: `npx @lumioui/cli add pro/navigation-rail-sidebar`

## Props

### NavigationRail

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | Controlled selected item. |
| `defaultValue?` | `string` | Uncontrolled initial selection. |
| `onValueChange?` | `(value: string) => void` | — |
| `expanded?` | `boolean` | Controlled expanded (sidebar) state. |
| `defaultExpanded?` | `boolean` | Uncontrolled initial expanded state. Default false. |
| `onExpandedChange?` | `(expanded: boolean) => void` | — |
| `mode?` | `"push" | "overlay"` | "push" resizes in the layout; "overlay" slides over the content with a scrim. Default "push". |
| `labels?` | `"always" | "selected" | "none"` | Labels under the icons while collapsed. Default "always". |
| `collapsedWidth?` | `number` | Collapsed width. Default 80. |
| `expandedWidth?` | `number` | Expanded width. Default 256. |
| `collapseOnSelect?` | `boolean` | Collapse after a pick in overlay mode. Default true. |
| `className?` | `string` | — |
| `children?` | `React.ReactNode` | — |

### NavigationRailItem

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `string` | Unique value — matched against the rail's value. |
| `icon` | `IconName` | — |
| `label` | `string` | — |
| `badge?` | `number | boolean` | Count badge, or `true` for a dot. |
| `disabled?` | `boolean` | — |
| `className?` | `string` | — |

### NavigationRailMenu

| Prop | Type | Notes |
| --- | --- | --- |
| `label?` | `string` | Accessibility label. Default "Navigation menu". |
| `className?` | `string` | — |

### NavigationRailFab

| Prop | Type | Notes |
| --- | --- | --- |
| `icon` | `IconName` | — |
| `label` | `string` | Shown when expanded (extended FAB) and used as the accessibility label. |
| `onPress?` | `() => void` | — |
| `className?` | `string` | — |

### NavigationRailSection

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | Heading shown when expanded; collapsed shows a short divider. |
| `className?` | `string` | — |

## Icons rendered

- `edit` — /icons.html?i=edit
- `mail` — /icons.html?i=mail
- `settings` — /icons.html?i=settings
- `menu` — /icons.html?i=menu
- `chevron-left` — /icons.html?i=chevron-left

Source: https://lumioui.com/components/navigation-rail