NavigationRail
The navigation rail lets you switch between primary pages on tablets and desktop computers.
Import the component:
import 'mdui/components/navigation-rail.js';
import 'mdui/components/navigation-rail-item.js';
Import the TypeScript type:
import type { NavigationRail } from 'mdui/components/navigation-rail.js';
import type { NavigationRailItem } from 'mdui/components/navigation-rail-item.js';
Example: (Note: The style="position: relative" in the example is for demonstration purposes. Don't include it in production.)
Recent
Images
Library
<mdui-navigation-rail value="recent" style="position: relative">
<mdui-navigation-rail-item icon="watch_later--outlined" value="recent">Recent</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="image--outlined" value="images">Images</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="library_music--outlined" value="library">Library</mdui-navigation-rail-item>
</mdui-navigation-rail>
Notes:
By default, this component uses the position: fixed style and automatically adds padding-left or padding-right to the body to prevent content from being obscured.
However, it falls back to position: absolute in the following cases:
- When the
contained property of the <mdui-navigation-rail> component is true. In this case, it adds padding-left or padding-right style to the parent element.
- When the component is used inside the
<mdui-layout></mdui-layout> component. In this case, padding-left or padding-right style is not added.
By default, the navigation rail appears on the left or right side of the viewport. To place it inside a container, add the contained attribute to the <mdui-navigation-rail> component. This makes the navigation rail position itself relative to the parent element (you need to add position: relative style to the parent element).
<div style="position: relative">
<mdui-navigation-rail contained>
<mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
</mdui-navigation-rail>
<div style="height: 260px;overflow: auto">
<div style="height: 1000px">Page Content</div>
</div>
</div>
Source
Set the placement attribute of the <mdui-navigation-rail> component to right to display the navigation rail on the right.
<div style="position: relative">
<mdui-navigation-rail placement="right" contained>
<mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
</mdui-navigation-rail>
<div style="height: 260px;overflow: auto">
<div style="height: 1000px">Page Content</div>
</div>
</div>
Source
Add the divider attribute to the <mdui-navigation-rail> component to add a divider to the navigation rail, distinguishing it from the page content.
<div style="position: relative">
<mdui-navigation-rail divider contained>
<mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
</mdui-navigation-rail>
<div style="height: 260px;overflow: auto">
<div style="height: 1000px">Page Content</div>
</div>
</div>
Source
Inside the <mdui-navigation-rail> component, you can use the top and bottom slots to add elements at the top and bottom.
<div style="position: relative">
<mdui-navigation-rail contained>
<mdui-button-icon icon="menu" slot="top"></mdui-button-icon>
<mdui-fab lowered icon="edit--outlined" slot="top"></mdui-fab>
<mdui-button-icon icon="settings" slot="bottom"></mdui-button-icon>
<mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
</mdui-navigation-rail>
<div style="height: 600px;overflow: auto">
<div style="height: 1000px">Page Content</div>
</div>
</div>
Source
Set the alignment attribute of the <mdui-navigation-rail> component to modify the vertical alignment of navigation items.
Recent
Images
Library
start
center
end
<div class="example-alignment" style="position: relative">
<mdui-navigation-rail alignment="start" contained>
<mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
</mdui-navigation-rail>
<div style="height: 360px;overflow: auto">
<mdui-segmented-button-group value="start" selects="single">
<mdui-segmented-button value="start">start</mdui-segmented-button>
<mdui-segmented-button value="center">center</mdui-segmented-button>
<mdui-segmented-button value="end">end</mdui-segmented-button>
</mdui-segmented-button-group>
</div>
</div>
<script>
const example = document.querySelector(".example-alignment");
const navigationRail = example.querySelector("mdui-navigation-rail");
const segmentedButtonGroup = example.querySelector("mdui-segmented-button-group");
segmentedButtonGroup.addEventListener("change", (event) => {
navigationRail.alignment = event.target.value;
});
</script>
Source
Use the icon attribute on the <mdui-navigation-rail-item> component to set the icon for the inactive state of the navigation item. The active-icon attribute sets the icon for the active state. Alternatively, use the icon and active-icon slots for the inactive and active states respectively.
<div style="position: relative">
<mdui-navigation-rail contained>
<mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="image--outlined" active-icon="image--filled">Images</mdui-navigation-rail-item>
<mdui-navigation-rail-item>
Library
<mdui-icon slot="icon" name="library_music--outlined"></mdui-icon>
<mdui-icon slot="active-icon" name="library_music--filled"></mdui-icon>
</mdui-navigation-rail-item>
</mdui-navigation-rail>
<div style="height: 260px;overflow: auto">
<div style="height: 1000px">Page Content</div>
</div>
</div>
Source
The <mdui-navigation-rail-item> component can display icons without labels.
<div style="position: relative">
<mdui-navigation-rail contained>
<mdui-navigation-rail-item icon="watch_later--outlined"></mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="image--outlined"></mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="library_music--outlined"></mdui-navigation-rail-item>
</mdui-navigation-rail>
<div style="height: 260px;overflow: auto">
<div style="height: 1000px">Page Content</div>
</div>
</div>
Source
Use the href attribute on the <mdui-navigation-rail-item> component to turn the navigation item into a link. The download, target, and rel attributes are available for link-related functionality.
<div style="position: relative">
<mdui-navigation-rail divider contained>
<mdui-navigation-rail-item
href="https://www.mdui.org"
target="_blank"
icon="watch_later--outlined"
>Recent</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
</mdui-navigation-rail>
<div style="height: 260px;overflow: auto">
<div style="height: 1000px">Page Content</div>
</div>
</div>
Source
Add a badge to the <mdui-navigation-rail-item> component using the badge slot.
Recent
99+
Images
Library
<div style="position: relative">
<mdui-navigation-rail contained>
<mdui-navigation-rail-item icon="watch_later--outlined">
Recent
<mdui-badge slot="badge">99+</mdui-badge>
</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
<mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
</mdui-navigation-rail>
<div style="height: 260px;overflow: auto">
<div style="height: 1000px">Page Content</div>
</div>
</div>
Source| Attribute | Property | Reflect | Type | Default |
|---|
icon | icon | | string | - |
Specifies the Material Icons name for the inactive state. Alternatively, use slot="icon".
|
active-icon | activeIcon | | string | - |
Specifies the Material Icons name for the active state. Alternatively, use slot="active-icon".
|
value | value | | string | - |
The value of the navigation item.
|
href | href | | string | - |
The URL for the link. When set, the component renders as an <a> element and supports link-related attributes.
|
download | download | | string | - |
Downloads the linked URL.
Note: Only available when href is specified.
|
target | target | | '_blank' | '_parent' | '_self' | '_top' | - |
Controls where the linked URL opens. Possible values:
_blank: Opens in a new tab or window._parent: Opens in the parent browsing context, or _self if there is no parent._self: Opens in the current browsing context (default)._top: Opens in the topmost browsing context, or _self if there are no ancestors.
Note: Only available when href is specified.
|
rel | rel | | 'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag' | - |
Specifies the relationship of the linked URL as space-separated link types. Possible values:
alternate: An alternate version of the current document.author: The author of the current document or article.bookmark: The permalink for the nearest ancestor section.external: The referenced document is not part of the same site as the current document.help: A link to context-sensitive help.license: Content covered by the copyright license described by the referenced document.me: Links to content owned by the current document's author.next: The next document in the series.nofollow: Not endorsed by the original author or publisher.noreferrer: Prevents the Referer header from being sent. Same effect as noopener.opener: Creates a new browsing context when the hyperlink would otherwise open in a top-level context that is not auxiliary (for example, when target="_blank" is specified).prev: The previous document in the series.search: Links to a resource that can be used to search through the current document and its related pages.tag: Marks the current document with the given tag.
Note: Only available when href is specified.
|
autofocus | autofocus | | boolean | false |
Whether the element is focused when the page loads.
|
tabindex | tabIndex | | number | - |
The element's tab order when navigating with the Tab key.
|
| Name | Parameters | Returns |
|---|
click | | void |
Simulates a mouse click on the element.
|
focus | options: FocusOptions (Optional)
| void |
Sets focus on the element. An optional object parameter may include a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.
|
blur | | void |
Removes focus from the element.
|
| Name |
|---|
focus |
Emitted when the navigation rail item gains focus.
|
blur |
Emitted when the navigation rail item loses focus.
|
| Attribute | Property | Reflect | Type | Default |
|---|
value | value | | string | - |
The value of the selected <mdui-navigation-rail-item>.
|
placement | placement | | 'left' | 'right' | 'left' |
Sets the navigation rail's position. Possible values:
left: Displays on the left.right: Displays on the right.
|
alignment | alignment | | 'start' | 'center' | 'end' | 'start' |
Sets the alignment of <mdui-navigation-rail-item> elements. Possible values:
start: Aligns to the top.center: Aligns to the center.end: Aligns to the bottom.
|
contained | contained | | boolean | false |
By default, the navigation rail is positioned relative to the body element. If set, it is positioned relative to its parent element.
Note: You must manually set position: relative; on the parent element when this attribute is set.
|
divider | divider | | boolean | false |
Adds a divider between the navigation rail and the page content.
|
order | order | | number | - |
Specifies the layout order within the <mdui-layout> component. Items are sorted in ascending order. The default value is 0.
|
| Name |
|---|
change |
Emitted when the value changes.
|
| Name |
|---|
| (default) |
Contains <mdui-navigation-rail-item> components.
|
top |
Top element.
|
bottom |
Bottom element.
|
| Name |
|---|
top |
Container for the top element.
|
bottom |
Container for the bottom element.
|
items |
Container for <mdui-navigation-rail-item> components.
|
| Name |
|---|
--shape-corner |
The corner radius of the component. You can use a specific pixel value, but it is recommended to reference design tokens.
|
--z-index |
The CSS z-index value of the component.
|
