NavigationRail

The navigation rail provides a means to access different primary pages on tablets and desktop computers.

Usage

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:

  1. 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.
  2. When it's within the <mdui-layout></mdui-layout> component. In this case, it doesn't add padding-left or padding-right style.

Styles

In Container

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).

Right Placement

Set the placement attribute of the <mdui-navigation-rail> component to right to display the navigation rail on the right.

Display a Divider

Add the divider attribute to the <mdui-navigation-rail> component to add a divider to the navigation rail, distinguishing it from the page content.

Top/Bottom Elements

Inside the <mdui-navigation-rail> component, you can use the top and bottom slots to add elements at the top and bottom.

Vertical Alignment

Set the alignment attribute of the <mdui-navigation-rail> component to modify the vertical alignment of navigation items.

Icons

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.

Icon Only

The <mdui-navigation-rail-item> component can display icons without labels.

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.

Badge

Add a badge to the <mdui-navigation-rail-item> component using the badge slot.

AttributePropertyReflectTypeDefault

The value of the selected <mdui-navigation-rail-item>.

Sets the navigation bar's position. Possible values:

  • left: Display on the left.
  • right: Display on the right.

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.

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.

Adds a divider between the navigation bar and the page content.

Specifies the layout order within the <mdui-layout> component. Items are sorted in ascending order. The default value is 0.

Name

Emitted when the value changes.

Name

Contains <mdui-navigation-rail-item> components.

Top element.

Bottom element.

Name

Container for the top element.

Container for the bottom element.

Container for <mdui-navigation-rail-item> components.

Name

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.

The CSS z-index value of the component.

AttributePropertyReflectTypeDefault

Specifies the Material Icons name for the inactive state. Alternatively, use slot="icon".

Specifies the Material Icons name for the active state. Alternatively, use slot="active-icon".

The value of the navigation item.

The URL for the hyperlink. If specified, the component renders as an <a> element and can use link-related attributes.

Instructs the browser to treat the linked URL as a download.

Note: This is only available when href is specified.

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.

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.

Determines if the element should be focused when the page loads.

Specifies the order in which the element receives focus when navigating with the Tab key.

NameParametersReturns

Simulates a mouse click on the element.

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.

Removes focus from the element.

Name

Emitted when the navigation rail item gains focus.

Emitted when the navigation rail item loses focus.

Name

Text.

Icon.

Icon for the active state.

Badge.

Name

Container for the navigation item.

Indicator.

Badge.

Icon.

Icon for the active state.

Text.

Name

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.

MDUIDocsEnglish简体中文LightDarkSystem
Preset Colors
Custom Color
Extract Color from Wallpaper
Select a Wallpaper
Getting Started
Introduction Installation Usage TypeScript Support IDE Support Localization Frequently Asked Questions
Styles
Dark Theme Dynamic Theme Typography Design Tokens
Frameworks
React Vue Angular
Components
Button ButtonIcon Fab SegmentedButton Chip Card Checkbox Radio Switch Slider RangeSlider List Collapse Tabs Dropdown Menu Select TextField LinearProgress CircularProgress Dialog Divider Avatar Badge Icon Tooltip Snackbar NavigationBar NavigationDrawer NavigationRail BottomAppBar TopAppBar Layout
Functions
JavaScript Library dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
Libraries
@mdui/icons