# Dropdown Component

The Dropdown component shows content in a pop-up menu. It is often used together with the Menu component.

## Usage {#usage}

Import the component:

```js
import 'mdui/components/dropdown.js';
```

Import the TypeScript type:

```ts
import type { Dropdown } from 'mdui/components/dropdown.js';
```

Example:

```html
<mdui-dropdown>
  <mdui-button slot="trigger">Open dropdown</mdui-button>
  <mdui-menu>
    <mdui-menu-item>Item 1</mdui-menu-item>
    <mdui-menu-item>Item 2</mdui-menu-item>
  </mdui-menu>
</mdui-dropdown>
```

## Examples {#examples}

### Disabled State {#example-disabled}

Add the `disabled` attribute to disable the dropdown.

```html
<mdui-dropdown disabled>
  <mdui-button slot="trigger">Open dropdown</mdui-button>
  <mdui-menu>
    <mdui-menu-item>Item 1</mdui-menu-item>
    <mdui-menu-item>Item 2</mdui-menu-item>
  </mdui-menu>
</mdui-dropdown>
```

### Placement {#example-placement}

Use the `placement` attribute to control where the dropdown opens.

```html
<mdui-dropdown placement="right-start">
  <mdui-button slot="trigger">Open dropdown</mdui-button>
  <mdui-menu>
    <mdui-menu-item>Item 1</mdui-menu-item>
    <mdui-menu-item>Item 2</mdui-menu-item>
  </mdui-menu>
</mdui-dropdown>
```

### Trigger Method {#example-trigger}

Use the `trigger` attribute to set how the dropdown opens.

```html
<mdui-dropdown trigger="hover">
  <mdui-button slot="trigger">Open dropdown</mdui-button>
  <mdui-menu>
    <mdui-menu-item>Item 1</mdui-menu-item>
    <mdui-menu-item>Item 2</mdui-menu-item>
  </mdui-menu>
</mdui-dropdown>
```

### Open on Pointer {#example-open-on-pointer}

Add the `open-on-pointer` attribute to open the dropdown at the pointer position. It is often paired with `trigger="contextmenu"` to open a context menu on right-click.

```html
<mdui-dropdown trigger="contextmenu" open-on-pointer>
  <mdui-card slot="trigger" style="width:100%;height: 80px">Right-click here to open the menu</mdui-card>
  <mdui-menu>
    <mdui-menu-item>Item 1</mdui-menu-item>
    <mdui-menu-item>Item 2</mdui-menu-item>
  </mdui-menu>
</mdui-dropdown>
```

### Keep Menu Open {#example-stay-open-on-click}

By default, clicking a menu item in the dropdown component closes it. Add `stay-open-on-click` to keep it open.

```html
<mdui-dropdown trigger="click" stay-open-on-click>
  <mdui-button slot="trigger">Open dropdown</mdui-button>
  <mdui-menu>
    <mdui-menu-item>Item 1</mdui-menu-item>
    <mdui-menu-item>Item 2</mdui-menu-item>
  </mdui-menu>
</mdui-dropdown>
```

### Open/Close Delay {#example-delay}

With `trigger="hover"`, use `open-delay` and `close-delay` to set the open and close delays.

```html
<mdui-dropdown trigger="hover" open-delay="1000" close-delay="1000">
  <mdui-button slot="trigger">Open dropdown</mdui-button>
  <mdui-menu>
    <mdui-menu-item>Item 1</mdui-menu-item>
    <mdui-menu-item>Item 2</mdui-menu-item>
  </mdui-menu>
</mdui-dropdown>
```

## mdui-dropdown 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 dropdown.</p>
</td>
  </tr>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Disables the dropdown.</p>
</td>
  </tr>
  <tr>
    <td>trigger</td>
    <td>trigger</td>
    <td>true</td>
    <td>&#39;click&#39; | &#39;hover&#39; | &#39;focus&#39; | &#39;contextmenu&#39; | &#39;manual&#39; | string</td>
    <td>'click'</td>
    <td><p>Defines how the dropdown opens. Multiple space-separated values are supported. Possible values:</p>
<ul>
<li><code>click</code>: Triggers on click.</li>
<li><code>hover</code>: Triggers on mouse hover.</li>
<li><code>focus</code>: Triggers on focus.</li>
<li><code>contextmenu</code>: Triggers on right-click or long press.</li>
<li><code>manual</code>: If used, the dropdown can only be opened and closed programmatically, and no other trigger methods can be specified.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>placement</td>
    <td>placement</td>
    <td>true</td>
    <td>&#39;auto&#39; | &#39;top-start&#39; | &#39;top&#39; | &#39;top-end&#39; | &#39;bottom-start&#39; | &#39;bottom&#39; | &#39;bottom-end&#39; | &#39;left-start&#39; | &#39;left&#39; | &#39;left-end&#39; | &#39;right-start&#39; | &#39;right&#39; | &#39;right-end&#39;</td>
    <td>'auto'</td>
    <td><p>Sets the dropdown position. Possible values:</p>
<ul>
<li><code>auto</code>: Automatically determined.</li>
<li><code>top-start</code>: Above and left-aligned.</li>
<li><code>top</code>: Above and centered.</li>
<li><code>top-end</code>: Above and right-aligned.</li>
<li><code>bottom-start</code>: Below and left-aligned.</li>
<li><code>bottom</code>: Below and centered.</li>
<li><code>bottom-end</code>: Below and right-aligned.</li>
<li><code>left-start</code>: Left and top-aligned.</li>
<li><code>left</code>: Left and centered.</li>
<li><code>left-end</code>: Left and bottom-aligned.</li>
<li><code>right-start</code>: Right and top-aligned.</li>
<li><code>right</code>: Right and centered.</li>
<li><code>right-end</code>: Right and bottom-aligned.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>stay-open-on-click</td>
    <td>stayOpenOnClick</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Prevents the dropdown from closing when a <a href="/en/docs/2/components/menu#menu-item-api"><code>&lt;mdui-menu-item&gt;</code></a> is clicked.</p>
</td>
  </tr>
  <tr>
    <td>open-delay</td>
    <td>openDelay</td>
    <td>true</td>
    <td>number</td>
    <td>150</td>
    <td><p>Sets the delay (in ms) for opening the dropdown on hover.</p>
</td>
  </tr>
  <tr>
    <td>close-delay</td>
    <td>closeDelay</td>
    <td>true</td>
    <td>number</td>
    <td>150</td>
    <td><p>Sets the delay (in ms) for closing the dropdown on hover.</p>
</td>
  </tr>
  <tr>
    <td>open-on-pointer</td>
    <td>openOnPointer</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Opens the dropdown at the pointer position. This is typically used for context menus.</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 dropdown starts to open. Can be prevented with <code>event.preventDefault()</code>.</p>
</td>
  </tr>
  <tr>
    <td>opened</td>
    <td><p>Emitted after the dropdown has opened and the animations are completed.</p>
</td>
  </tr>
  <tr>
    <td>close</td>
    <td><p>Emitted when the dropdown starts to close. Can be prevented with <code>event.preventDefault()</code>.</p>
</td>
  </tr>
  <tr>
    <td>closed</td>
    <td><p>Emitted after the dropdown has closed and the animations are completed.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>The content of the dropdown.</p>
</td>
  </tr>
  <tr>
    <td>trigger</td>
    <td><p>The element that triggers the dropdown, such as an <a href="/en/docs/2/components/button"><code>&lt;mdui-button&gt;</code></a> element.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>trigger</td>
    <td><p>Container for the element that triggers the dropdown; this is the <code>trigger</code> slot container.</p>
</td>
  </tr>
  <tr>
    <td>panel</td>
    <td><p>The container of the dropdown content.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Custom Properties

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--z-index</td>
    <td><p>The CSS <code>z-index</code> value of the component.</p>
</td>
  </tr>
</tbody>
</table>