# Navigation Drawer Component

The navigation drawer provides side navigation between pages on a website.

Typically, the [`<mdui-list>`](/en/docs/2/components/list) component is used within the navigation drawer to add navigation items.

## Usage {#usage}

Import the component:

```js
import 'mdui/components/navigation-drawer.js';
```

Import the TypeScript type:

```ts
import type { NavigationDrawer } from 'mdui/components/navigation-drawer.js';
```

Example:

```html
<mdui-navigation-drawer close-on-overlay-click class="example-drawer">
  <mdui-button>Close Navigation Drawer</mdui-button>
</mdui-navigation-drawer>

<mdui-button>Open Navigation Drawer</mdui-button>

<script>
  const navigationDrawer = document.querySelector(".example-drawer");
  const openButton = navigationDrawer.nextElementSibling;
  const closeButton = navigationDrawer.querySelector("mdui-button");

  openButton.addEventListener("click", () => navigationDrawer.open = true);
  closeButton.addEventListener("click", () => navigationDrawer.open = false);
</script>
```

**Notes:**

By default, this component uses `position: fixed`.

When `modal` is `false` and the breakpoint is at least [`--mdui-breakpoint-md`](/en/docs/2/styles/design-tokens#breakpoint), it automatically adds `padding-left` or `padding-right` to the body to prevent content from being obscured.

However, it uses a `position: absolute` style in the following cases:

1. When the `contained` property is `true`.
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` is not added.

## Examples {#examples}

### In Container {#example-contained}

By default, the navigation drawer appears on the left or right side of the viewport. To place it inside a container, add the `contained` attribute. This makes the navigation drawer position itself relative to the parent element (you need to add `position: relative; overflow: hidden;` styles to the parent element).

```html
<div class="example-contained" style="position: relative; overflow: hidden">
  <mdui-navigation-drawer contained>
    <mdui-button class="close">Close Navigation Drawer</mdui-button>
  </mdui-navigation-drawer>

  <div style="height: 160px;">
    <mdui-button class="open">Open Navigation Drawer</mdui-button>
  </div>
</div>

<script>
  const example = document.querySelector(".example-contained");
  const navigationDrawer = example.querySelector("mdui-navigation-drawer");
  const openButton = example.querySelector(".open");
  const closeButton = example.querySelector(".close");

  openButton.addEventListener("click", () => navigationDrawer.open = true);
  closeButton.addEventListener("click", () => navigationDrawer.open = false);
</script>
```

### Modal {#example-modal}

The `modal` attribute displays a modal overlay when the navigation drawer is open. Note that if the window or parent element width is less than [`--mdui-breakpoint-md`](/en/docs/2/styles/design-tokens#breakpoint), this attribute is ignored and the modal overlay is always displayed.

The `close-on-esc` attribute lets the navigation drawer close when the ESC key is pressed.

The `close-on-overlay-click` attribute lets the navigation drawer close when the modal overlay is clicked.

```html
<div class="example-modal" style="position: relative; overflow: hidden">
  <mdui-navigation-drawer modal close-on-esc close-on-overlay-click contained>
    <mdui-button class="close">Close Navigation Drawer</mdui-button>
  </mdui-navigation-drawer>

  <div style="height: 160px;">
    <mdui-button class="open">Open Navigation Drawer</mdui-button>
  </div>
</div>

<script>
  const example = document.querySelector(".example-modal");
  const navigationDrawer = example.querySelector("mdui-navigation-drawer");
  const openButton = example.querySelector(".open");
  const closeButton = example.querySelector(".close");

  openButton.addEventListener("click", () => navigationDrawer.open = true);
  closeButton.addEventListener("click", () => navigationDrawer.open = false);
</script>
```

### Right Placement {#example-placement}

Use the `placement` attribute to place the navigation drawer on the right side.

```html
<div class="example-placement" style="position: relative; overflow: hidden">
  <mdui-navigation-drawer placement="right" modal close-on-esc close-on-overlay-click contained>
    <mdui-button class="close">Close Navigation Drawer</mdui-button>
  </mdui-navigation-drawer>

  <div style="height: 160px;">
    <mdui-button class="open">Open Navigation Drawer</mdui-button>
  </div>
</div>

<script>
  const example = document.querySelector(".example-placement");
  const navigationDrawer = example.querySelector("mdui-navigation-drawer");
  const openButton = example.querySelector(".open");
  const closeButton = example.querySelector(".close");

  openButton.addEventListener("click", () => navigationDrawer.open = true);
  closeButton.addEventListener("click", () => navigationDrawer.open = false);
</script>
```

## mdui-navigation-drawer 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>open</td>
    <td>open</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Opens the navigation drawer.</p>
</td>
  </tr>
  <tr>
    <td>modal</td>
    <td>modal</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Displays an overlay when open.</p>
<p>On narrow devices (screen width &lt; <a href="/en/docs/2/styles/design-tokens#breakpoint"><code>--mdui-breakpoint-md</code></a>), the overlay is always displayed.</p>
</td>
  </tr>
  <tr>
    <td>close-on-esc</td>
    <td>closeOnEsc</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Closes the drawer when the ESC key is pressed and an overlay is present.</p>
</td>
  </tr>
  <tr>
    <td>close-on-overlay-click</td>
    <td>closeOnOverlayClick</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Closes the drawer when the overlay is clicked.</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 drawer&#39;s position. Possible values:</p>
<ul>
<li><code>left</code>: Displays on the left side.</li>
<li><code>right</code>: Displays on the right side.</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 drawer 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; overflow: hidden;</code> on the parent element when this attribute is set.</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>open</td>
    <td><p>Emitted when the navigation drawer starts to open. Can be prevented with <code>event.preventDefault()</code>.</p>
</td>
  </tr>
  <tr>
    <td>opened</td>
    <td><p>Emitted after the navigation drawer has opened and the animations are completed.</p>
</td>
  </tr>
  <tr>
    <td>close</td>
    <td><p>Emitted when the navigation drawer starts to close. Can be prevented with <code>event.preventDefault()</code>.</p>
</td>
  </tr>
  <tr>
    <td>closed</td>
    <td><p>Emitted after the navigation drawer has closed and the animations are completed.</p>
</td>
  </tr>
  <tr>
    <td>overlay-click</td>
    <td><p>Emitted when the overlay is clicked.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Contents of the navigation drawer.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>overlay</td>
    <td><p>Overlay element.</p>
</td>
  </tr>
  <tr>
    <td>panel</td>
    <td><p>Container for the navigation drawer.</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>