# Navigation Rail Component

The navigation rail lets you switch between primary pages on tablets and desktop computers.

## Usage {#usage}

Import the component:

```js
import 'mdui/components/navigation-rail.js';
import 'mdui/components/navigation-rail-item.js';
```

Import the TypeScript type:

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

```html
<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:

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 the component is used inside the [`<mdui-layout></mdui-layout>`](/en/docs/2/components/layout) component. In this case, `padding-left` or `padding-right` style is not added.

## Examples {#examples}

### In Container {#example-contained}

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

```html
<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>
```

### Right Placement {#example-placement}

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

```html
<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>
```

### Display a Divider {#example-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.

```html
<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>
```

### Top/Bottom Elements {#example-top-bottom}

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

```html
<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>
```

### Vertical Alignment {#example-alignment}

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

```html
<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>
```

### Icons {#example-icon}

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.

```html
<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>
```

### Icon Only {#example-no-label}

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

```html
<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>
```

### Link {#example-link}

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.

```html
<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>
```

### Badge {#example-badge}

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

```html
<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>
```

## mdui-navigation-rail-item API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Specifies the Material Icons name for the inactive state. Alternatively, use <code>slot=&quot;icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>active-icon</td>
    <td>activeIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Specifies the Material Icons name for the active state. Alternatively, use <code>slot=&quot;active-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>The value of the navigation item.</p>
</td>
  </tr>
  <tr>
    <td>href</td>
    <td>href</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>The URL for the link. When set, the component renders as an <code>&lt;a&gt;</code> element and supports link-related attributes.</p>
</td>
  </tr>
  <tr>
    <td>download</td>
    <td>download</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Downloads the linked URL.</p>
<p><strong>Note</strong>: Only available when <code>href</code> is specified.</p>
</td>
  </tr>
  <tr>
    <td>target</td>
    <td>target</td>
    <td>true</td>
    <td>&#39;_blank&#39; | &#39;_parent&#39; | &#39;_self&#39; | &#39;_top&#39;</td>
    <td></td>
    <td><p>Controls where the linked URL opens. Possible values:</p>
<ul>
<li><code>_blank</code>: Opens in a new tab or window.</li>
<li><code>_parent</code>: Opens in the parent browsing context, or <code>_self</code> if there is no parent.</li>
<li><code>_self</code>: Opens in the current browsing context (default).</li>
<li><code>_top</code>: Opens in the topmost browsing context, or <code>_self</code> if there are no ancestors.</li>
</ul>
<p><strong>Note</strong>: Only available when <code>href</code> is specified.</p>
</td>
  </tr>
  <tr>
    <td>rel</td>
    <td>rel</td>
    <td>true</td>
    <td>&#39;alternate&#39; | &#39;author&#39; | &#39;bookmark&#39; | &#39;external&#39; | &#39;help&#39; | &#39;license&#39; | &#39;me&#39; | &#39;next&#39; | &#39;nofollow&#39; | &#39;noreferrer&#39; | &#39;opener&#39; | &#39;prev&#39; | &#39;search&#39; | &#39;tag&#39;</td>
    <td></td>
    <td><p>Specifies the relationship of the linked URL as space-separated link types. Possible values:</p>
<ul>
<li><code>alternate</code>: An alternate version of the current document.</li>
<li><code>author</code>: The author of the current document or article.</li>
<li><code>bookmark</code>: The permalink for the nearest ancestor section.</li>
<li><code>external</code>: The referenced document is not part of the same site as the current document.</li>
<li><code>help</code>: A link to context-sensitive help.</li>
<li><code>license</code>: Content covered by the copyright license described by the referenced document.</li>
<li><code>me</code>: Links to content owned by the current document&#39;s author.</li>
<li><code>next</code>: The next document in the series.</li>
<li><code>nofollow</code>: Not endorsed by the original author or publisher.</li>
<li><code>noreferrer</code>: Prevents the <code>Referer</code> header from being sent. Same effect as <code>noopener</code>.</li>
<li><code>opener</code>: Creates a new browsing context when the hyperlink would otherwise open in a top-level context that is not auxiliary (for example, when <code>target=&quot;_blank&quot;</code> is specified).</li>
<li><code>prev</code>: The previous document in the series.</li>
<li><code>search</code>: Links to a resource that can be used to search through the current document and its related pages.</li>
<li><code>tag</code>: Marks the current document with the given tag.</li>
</ul>
<p><strong>Note</strong>: Only available when <code>href</code> is specified.</p>
</td>
  </tr>
  <tr>
    <td>autofocus</td>
    <td>autofocus</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Whether the element is focused when the page loads.</p>
</td>
  </tr>
  <tr>
    <td>tabindex</td>
    <td>tabIndex</td>
    <td>false</td>
    <td>number</td>
    <td></td>
    <td><p>The element&#39;s tab order when navigating with the Tab key.</p>
</td>
  </tr>
</tbody>
</table>

### Methods

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>click(): void</td>
    <td><p>Simulates a mouse click on the element.</p>
</td>
  </tr>
  <tr>
    <td>focus(options?: FocusOptions): void</td>
    <td><p>Sets focus on the element. An optional object parameter may include a <code>preventScroll</code> property. If <code>preventScroll</code> is set to <code>true</code>, the page will not scroll to bring the focused element into view.</p>
</td>
  </tr>
  <tr>
    <td>blur(): void</td>
    <td><p>Removes focus from the element.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>focus</td>
    <td><p>Emitted when the navigation rail item gains focus.</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>Emitted when the navigation rail item loses focus.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Text.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Icon.</p>
</td>
  </tr>
  <tr>
    <td>active-icon</td>
    <td><p>Icon for the active state.</p>
</td>
  </tr>
  <tr>
    <td>badge</td>
    <td><p>Badge.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>container</td>
    <td><p>Container for the navigation item.</p>
</td>
  </tr>
  <tr>
    <td>indicator</td>
    <td><p>Indicator.</p>
</td>
  </tr>
  <tr>
    <td>badge</td>
    <td><p>Badge.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Icon.</p>
</td>
  </tr>
  <tr>
    <td>active-icon</td>
    <td><p>Icon for the active state.</p>
</td>
  </tr>
  <tr>
    <td>label</td>
    <td><p>Text.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Custom Properties

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner-indicator</td>
    <td><p>The corner radius of the indicator. You can use a specific pixel value, but it is recommended to reference <a href="/en/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
</tbody>
</table>

## mdui-navigation-rail API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>The value of the selected <code>&lt;mdui-navigation-rail-item&gt;</code>.</p>
</td>
  </tr>
  <tr>
    <td>placement</td>
    <td>placement</td>
    <td>true</td>
    <td>&#39;left&#39; | &#39;right&#39;</td>
    <td>'left'</td>
    <td><p>Sets the navigation rail&#39;s position. Possible values:</p>
<ul>
<li><code>left</code>: Displays on the left.</li>
<li><code>right</code>: Displays on the right.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>alignment</td>
    <td>alignment</td>
    <td>true</td>
    <td>&#39;start&#39; | &#39;center&#39; | &#39;end&#39;</td>
    <td>'start'</td>
    <td><p>Sets the alignment of <code>&lt;mdui-navigation-rail-item&gt;</code> elements. Possible values:</p>
<ul>
<li><code>start</code>: Aligns to the top.</li>
<li><code>center</code>: Aligns to the center.</li>
<li><code>end</code>: Aligns to the bottom.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>contained</td>
    <td>contained</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>By default, the navigation rail is positioned relative to the <code>body</code> element. If set, it is positioned relative to its parent element.</p>
<p><strong>Note</strong>: You must manually set <code>position: relative;</code> on the parent element when this attribute is set.</p>
</td>
  </tr>
  <tr>
    <td>divider</td>
    <td>divider</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Adds a divider between the navigation rail and the page content.</p>
</td>
  </tr>
  <tr>
    <td>order</td>
    <td>order</td>
    <td>true</td>
    <td>number</td>
    <td></td>
    <td><p>Specifies the layout order within the <a href="/en/docs/2/components/layout"><code>&lt;mdui-layout&gt;</code></a> component. Items are sorted in ascending order. The default value is <code>0</code>.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>change</td>
    <td><p>Emitted when the value changes.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Contains <code>&lt;mdui-navigation-rail-item&gt;</code> components.</p>
</td>
  </tr>
  <tr>
    <td>top</td>
    <td><p>Top element.</p>
</td>
  </tr>
  <tr>
    <td>bottom</td>
    <td><p>Bottom element.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>top</td>
    <td><p>Container for the top element.</p>
</td>
  </tr>
  <tr>
    <td>bottom</td>
    <td><p>Container for the bottom element.</p>
</td>
  </tr>
  <tr>
    <td>items</td>
    <td><p>Container for <code>&lt;mdui-navigation-rail-item&gt;</code> components.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Custom Properties

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner</td>
    <td><p>The corner radius of the component. You can use a specific pixel value, but it is recommended to reference <a href="/en/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
  <tr>
    <td>--z-index</td>
    <td><p>The CSS <code>z-index</code> value of the component.</p>
</td>
  </tr>
</tbody>
</table>