# Navigation Rail A navigation rail lets people switch between top-level destinations on larger windows, and expands to show full labels. **Example: A navigation rail with a menu button and four destinations** ```html mail Inbox chat_bubble Chat groups Spaces videocam Meet ``` ## Usage guidelines * **Use it in medium windows and larger.** On compact windows use a [navigation bar](/material-web/3.0/components/navigation-bar/) instead. * **Keep three to seven destinations.** Add an optional FAB or menu button in the header. * **Keep it in the same place.** The rail stays at the leading edge on every screen of the app. * **Let it expand.** A [collapsed](#collapsible) rail shows icons and short labels, and an expanded rail shows horizontal items and can replace a navigation drawer. This component is new in [M3 Expressive](https://m3.material.io/blog/building-with-m3-expressive). ## Anatomy A rail has an optional header, such as a menu button or a FAB, and items. Each item has an icon, a label and an optional badge. **Example: A rail with a menu button, a FAB and items, one with a badge** ```html menu edit inbox 3 Inbox send Sent ``` ## Examples ### Links Give an item an `href` (and optionally `target` and `rel`) to make the destination a link, as in the first example. The item then has the `link` role and the selected one is marked `aria-current="page"`. Without `href` an item is a tab that just reports the selection. ### Collapsible Add `collapsible` to show a built-in menu button in the header that expands and collapses the rail. To use your own button, put it in the `header` slot and call `toggle()`, `expand()` or `collapse()`. Set `expanded` to start expanded. The rail fires `toggle` when it expands or collapses. **Example: A collapsible rail that starts expanded** ```html mail Inbox send Sent drafts Drafts ``` ### Header Use the `header` slot for a menu button and a FAB above the items. **Example: A rail with a menu button and a compose FAB** ```html menu edit mail Inbox send Sent ``` ### Alignment Set `alignment` to `top` (the default), `center` or `bottom` to place the items along the rail. **Example: A rail with its items centered** ```html home Home search Search settings Settings ``` ### Badges Set `badge` on an item to show a count, or `badge="dot"` for a small dot. **Example: Rail items with a count badge and a dot badge** ```html mail Inbox chat_bubble Chat ``` ### Secondary items Add `secondary` to an item that should show only while the rail is expanded, such as a less important destination. **Example: An expanded rail with a secondary destination** ```html mail Inbox delete Trash ``` ### Modal Add `modal` so the expanded rail opens over the content with a scrim. Add `hide-when-collapsed` to take the collapsed rail out of the layout entirely; the app's menu button then calls `toggle()` to show it. On Android, the back gesture collapses a modal rail. **Example: A collapsible modal rail** ```html mail Inbox send Sent ``` ### Appearance Add `divider` to draw a line at the rail's edge, `elevated` to lift it above scrolling content, and `narrow` to use the 80dp collapsed width. **Example: A narrow rail with a divider** ```html home Home search Search ``` ## Accessibility * Give the rail an `aria-label` such as "Primary navigation". * Without links the rail is a tab list and its items are tabs, with exactly one selected. Tab moves focus into the rail, the arrow keys move between items, and Enter and Space select one. * When the items have an `href` the rail is a navigation landmark of links and the selected one is `aria-current="page"`. Enter follows a link; Space doesn't. * Every item needs a visible label, which is also its accessible name. * Give a menu button in the header an `aria-label`, such as "Open menu". * A modal rail collapses on Escape and when the scrim is pressed. Keep the menu button available as the single-pointer alternative to swiping it closed. * Disabled items leave the tab order. ## API reference ### <md-gb-nav-rail> A Material Design navigation rail custom element. #### Properties | Property | Attribute | Type | Default | | --- | --- | --- | --- | | alignment
Vertical alignment of items ('top', 'center', or 'bottom'). | alignment | NavRailAlignment | 'top' | | autoSelect
Whether or not to automatically select a tab when it is focused. | autoselect | boolean | false | | collapsible
Whether the navigation rail renders a built-in expand/collapse menu button in the header when no toggle button is slotted into slot="header". | collapsible | boolean | false | | divider
Whether a vertical divider marks the edge of the rail next to the app's content. | divider | boolean | false | | elevated
Whether the rail is elevated to level 1, to distinguish it from content that scrolls underneath it. | elevated | boolean | false | | expanded
Whether the navigation rail is expanded to show horizontal items. | expanded | boolean | false | | hideWhenCollapsed
Hide when collapsed (navigation-rail.md): the collapsed rail is not shown and takes no space, so the body content fills in. The expanded rail (always modal in this mode) appears over the content when the app's menu button calls expand() or toggle(); keep that menu button accessible. | hide-when-collapsed | boolean | false | | itemLayout
The layout orientation of items ('vertical' or 'horizontal'). | item-layout | NavRailItemLayout | 'vertical' | | modal
Whether the expanded navigation rail is modal: it opens over the content with a scrim, with modal elevation and shape. | modal | boolean | false | | narrow
Whether the collapsed rail uses the narrow width (md.comp.nav-rail.collapsed.narrow.container.width, 80dp). | narrow | boolean | false | | selectedIndex
The 0-based index of the currently active navigation rail item. Alias for selectedTabIndex. | selected-index | number | | | selectedTabIndex
The index of the currently selected tab. | selectedtabindex | number | | #### Slots | Slot | Description | | --- | --- | | default | Used to display navigation rail items (md-gb-nav-rail-item). | | header | Used to display optional header controls (menu button, FAB). | #### Events | Event | Description | | --- | --- | | change
Event | Fired when the selected item changes. | | toggle
CustomEvent<{expanded: boolean, reason?: string}> | Fired when the expanded state is toggled. | #### Methods | Method | Description | | --- | --- | | collapse
() => void | Collapses the navigation rail. | | expand
() => void | Expands the navigation rail. | | handleBack
() => Promise<void> | Handles a back request (the Android back gesture or button) on the modal expanded rail: plays the predictive back motion, then collapses the rail. Call it for an in-app back control that should behave like the system back. Resolves after the back motion. | | toggle
(force?: boolean) => boolean | Toggles the expanded state of the navigation rail. | #### CSS parts | Part | Description | | --- | --- | | ::part(header) | The navigation rail's header container. | | ::part(items) | The navigation rail's items container. | | ::part(menu-button) | The built-in expand/collapse menu button when collapsible. | | ::part(nav-rail) | The navigation rail's root container. | | ::part(scrim) | The modal rail's scrim, while expanded. A modal rail expands over the content with a scrim, like Compose ModalWideNavigationRail. Clicking the scrim, pressing Escape or swiping the rail toward its edge collapses it. The scrim (and the menu button of a collapsible rail) are the single-pointer alternatives to the swipe. While a modal rail is expanded, focus moves into it, Tab stays inside it, page scrolling is locked, and focus returns to the previous element when it collapses. The toggle event's detail.reason says why a modal rail collapsed (escape, back, scrim or swipe). Predictive back applies to the modal expanded rail (navigation-rail.md): while it is expanded the rail listens for back requests with a CloseWatcher (the Android back gesture or button, and Escape), falling back to Escape on the document where CloseWatcher is missing. A back request plays the predictive back motion (the rail pops off its edge, Compose ModalWideNavigationRail scales) and collapses the rail. A FAB (md-gb-fab with a label) in the header is an extended FAB while the rail is expanded and an icon FAB while it is collapsed. | #### CSS custom properties | Property | Description | | --- | --- | | --collapsed-item-vertical-space | | | --collapsed-narrow-container-width | | | --collapsed-top-space | | | --container-color | | | --container-elevation | | | --container-shape | | | --container-vertical-padding | | | --container-width | | | --expanded-container-color | | | --expanded-container-width-maximum | | | --expanded-container-width-minimum | | | --expanded-modal-container-color | | | --expanded-top-space | | | --header-space-minimum | | | --item-active-focused-icon-color | | | --item-active-focused-label-text-color | | | --item-active-hovered-icon-color | | | --item-active-hovered-label-text-color | | | --item-active-icon-color | | | --item-active-indicator-color | | | --item-active-indicator-height | | | --item-active-indicator-shape | | | --item-active-indicator-width | | | --item-active-label-text-color | | | --item-active-pressed-icon-color | | | --item-active-pressed-label-text-color | | | --item-active-state-layer-color | | | --item-container-height | | | --item-container-vertical-space | | | --item-full-width-leading-space | | | --item-full-width-trailing-space | | | --item-horizontal-active-indicator-height | | | --item-horizontal-active-indicator-width | The expanded destinations' pill width: fit-content (default) hugs the icon and label; 100% takes the destination's width. | | --item-horizontal-icon-label-space | | | --item-icon-size | | | --item-inactive-focused-icon-color | | | --item-inactive-focused-label-text-color | | | --item-inactive-hovered-icon-color | | | --item-inactive-hovered-label-text-color | | | --item-inactive-icon-color | | | --item-inactive-label-text-color | | | --item-inactive-pressed-icon-color | | | --item-inactive-pressed-label-text-color | | | --item-inactive-state-layer-color | | | --item-label-text-font | | | --item-label-text-font-axes | | | --item-label-text-font-tracking | | | --item-outer-space | | | --item-vertical-icon-label-space | | | --item-vertical-leading-space | | | --item-vertical-trailing-space | | | --modal-container-elevation | | | --modal-container-shape | | | --modal-scrim-color | | | --motion-duration | | | --motion-easing | | ### <md-gb-nav-rail-item> A Material Design navigation rail item custom element. #### Properties | Property | Attribute | Type | Default | | --- | --- | --- | --- | | active
Whether the navigation rail item is active. Alias for selected. TODO: replace reflected [active] with :state(selected) | active | boolean | | | badge
Optional badge text (or 'dot' / 'true' for a small dot badge). | badge | string | '' | | disabled
Whether the navigation rail item is disabled. | disabled | boolean | false | | href
The URL the destination links to. The item is then a link (role link, aria-current="page" while selected) instead of a tab. | href | string | '' | | itemLayout
The layout orientation of the item ('vertical' or 'horizontal'). | item-layout | NavRailItemLayout | 'vertical' | | label
Optional label text if not provided via default slot. | label | string | '' | | rel
The link's rel attribute, when href is set. | rel | string | '' | | secondary
Whether the destination is secondary: it shows only while the rail is expanded. | secondary | boolean | false | | tabpanel
ID of the associated md-aria-tabpanel element. | tabpanel | string | | | target
Where to open the linked href, e.g. _blank. | target | "" | "_blank" | "_parent" | "_self" | "_top" | '' | | unfilledIcon
Whether the icon has no filled style. The active destination then uses the semibold icon weight instead of the filled icon. | unfilled-icon | boolean | false | #### Slots | Slot | Description | | --- | --- | | default | Used to display the item's label text. | | badge | Used to display a custom badge on the item's icon. | | icon | Used to display the item's icon (md-gb-icon). | #### Methods | Method | Description | | --- | --- | | click
() => void | Activates the destination: follows its link, else clicks the tab. | #### CSS parts | Part | Description | | --- | --- | | ::part(indicator) | The active indicator / icon container element. | | ::part(label) | The label text container element. | | ::part(nav-rail-item) | The navigation rail item's presentational container. |