NavigationRail
The navigation rail provides a means to access different 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, Remove it in actual use.)
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 obscuration.
However, it defaults to position: absolute style 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 it's within the
<mdui-layout></mdui-layout> component. In this case, it doesn't add padding-left or padding-right style.
By default, the navigation rail displays on the left or right side of the current window. To place it inside a container, add the contained attribute to the <mdui-navigation-rail> component. This positions the navigation rail relative to the parent element (you need to manually 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>
Code
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>
Code
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>
Code
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>
Code
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>
Code
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>
Code
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>
Code
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>
Code
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>
Code| 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 hyperlink. If specified, the component renders as an <a> element and can use link-related attributes.
|
download | download | | string | - |
Instructs the browser to treat the linked URL as a download.
Note: This is only available when href is specified.
|
target | target | | '_blank' | '_parent' | '_self' | '_top' | - |
Defines where to display the linked URL. Possible values:
_blank: Opens in a new tab or window._parent: Opens in the parent browsing context or _self if no parent exists._self: Opens in the current browsing context. (Default)._top: Opens in the topmost browsing context or _self if no ancestors exist.
Note: This is 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: Alternate versions of the current document.author: Author of the current document or article.bookmark: Permanent link for the nearest ancestor section.external: The referenced document is not part of the same site as the current document.help: Link to context-sensitive help.license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.me: Indicates that the current document represents the person who owns the linked content.next: Indicates that the current document is part of a series and the next document in the series is the referenced document.nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.noreferrer: No Referer header will be included. Also has the same effect as noopener.opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.search: Links to a resource that can be used to search through the current document and its related pages.tag: Gives a tag (identified by the given address) that applies to the current document.
Note: This is only available when href is specified.
|
autofocus | autofocus | | boolean | false |
Determines if the element should be focused when the page loads.
|
tabindex | tabIndex | | number | - |
Specifies the order in which the element receives focus 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 parameter can be an object with 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 bar's position. Possible values:
left: Display on the left.right: Display on the right.
|
alignment | alignment | | 'start' | 'center' | 'end' | 'start' |
Sets the alignment of <mdui-navigation-rail-item>. 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 displays relative to the body element. When set, it displays relative to its parent element.
Note: You must add position: relative; overflow: hidden; style to the parent element when this attribute is set.
|
divider | divider | | boolean | false |
Adds a divider between the navigation bar 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 size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
|
--z-index |
The CSS z-index value of the component.
|