# <aihio-dropdown>

A menu of actions or links opened from a trigger button, such as an account menu or a row's More actions. Not for choosing a form value: use aihio-combobox for that.

Intents: `menu`, `overlay`, `dismissible`.

## Attributes

- `open` (boolean): Whether the dropdown is open. Default: `false`.
- `align` (`start` | `end`): Alignment of the dropdown content relative to the trigger. Default: `start`.

## Methods

- `open()`: Opens the menu in the browser top layer.
- `close()`: Requests that the menu close.
- `toggle()`: Toggles the menu.

## Events

- `aihio-open`: Fired after the menu opens.
- `aihio-close` (detail: reason: string): Fired after the menu closes.
- `aihio-before-close` (detail: reason: string): Cancelable request fired before the menu closes.

## Slots

- `trigger`: The element that opens the dropdown. Must be focusable.
- `default`: Dropdown items and separators.

## <aihio-dropdown-item>

A selectable item in the dropdown. Give it a single <a href> child to make it a link.

### <aihio-dropdown-item> attributes

- `value` (string): Item value (defaults to text content).
- `disabled` (boolean): undefined. Default: `false`.

### Events

- `aihio-select` (detail: value: string): Fired when the item is selected.

## <aihio-dropdown-separator>

A visual separator between dropdown items.

## Accessibility obligations

- (error, dropdown-trigger-name) When the trigger is icon-only: Provide aria-label on the trigger (e.g. aria-label="Open menu").

## Examples

### A menu of actions

```html
<aihio-dropdown>
  <aihio-button slot="trigger" variant="outline">Open</aihio-button>
  <aihio-dropdown-item>Profile</aihio-dropdown-item>
  <aihio-dropdown-item>Settings</aihio-dropdown-item>
  <aihio-dropdown-separator></aihio-dropdown-separator>
  <aihio-dropdown-item>Logout</aihio-dropdown-item>
</aihio-dropdown>
```

### An account menu with links

An item whose child is an <a href> is a real link.

```html
<aihio-dropdown align="end">
  <aihio-button slot="trigger" variant="ghost">Account</aihio-button>
  <aihio-dropdown-item><a href="/profile">Profile</a></aihio-dropdown-item>
  <aihio-dropdown-item><a href="/settings">Settings</a></aihio-dropdown-item>
  <aihio-dropdown-separator></aihio-dropdown-separator>
  <aihio-dropdown-item value="sign-out">Sign out</aihio-dropdown-item>
</aihio-dropdown>
```

## Mistakes

### Missing slot="trigger". The dropdown has nothing to open it.

Don't (aihio lint: missing-required-slot):

```html
<aihio-dropdown>
  <aihio-dropdown-item>Profile</aihio-dropdown-item>
</aihio-dropdown>
```

Do:

```html
<aihio-dropdown>
  <aihio-button slot="trigger" variant="outline">Account</aihio-button>
  <aihio-dropdown-item>Profile</aihio-dropdown-item>
</aihio-dropdown>
```

### Children should be aihio-dropdown-item/separator so keyboard navigation and menuitem roles work. Put the link inside an item: <aihio-dropdown-item><a href="/x">Link</a></aihio-dropdown-item>.

Don't (aihio lint: invalid-child):

```html
<aihio-dropdown>
  <aihio-button slot="trigger">Menu</aihio-button>
  <a href="/x">Link</a>
</aihio-dropdown>
```

Do:

```html
<aihio-dropdown>
  <aihio-button slot="trigger">Menu</aihio-button>
  <aihio-dropdown-item><a href="/x">Link</a></aihio-dropdown-item>
</aihio-dropdown>
```