# Menu

A cascading action menu driven by a JSON items tree — actions, headings, separators, checkboxes, and submenus.

<p class="kai-tag-sub">kai-menu</p>

A cascading action menu you describe with data, not markup. Hand it a tree of items — actions, headings, separators, checkboxes, submenus — and it builds the dropdown, handles keyboard nav, and tells you what was picked.

## Preview

> **tip:** 
Reach for it when you have a small set of fixed actions behind a button — the `+` add-content menu next to a composer, a row-level `⋯` overflow, a select-style picker. The item tree carries nesting, shortcuts, and checkbox state, so you don't wire up positioning or roles yourself. For a searchable, type-to-filter list of actions, use [Command](/components/command/). To anchor arbitrary content (not a list of actions) to a trigger, use [Popover](/components/popover/).

## Usage

Build the menu from its `items` tree, set in JavaScript — arrays can't be HTML attributes. Each item is an action (`id` + `label`, optional `icon`/`shortcut`), a `heading`, a `separator`, a checkbox (add `checked`), or a submenu (nest more `items`). Selecting a leaf fires `kai-select` with its `id`; checkbox items also report the new `checked` value.

The trigger is the built-in button — point `trigger-icon` / `trigger-label` at it — or your own element in `slot="trigger"`.

```html
<kai-menu trigger-icon="plus" label="Add content"></kai-menu>

<script type="module">

  const menu = document.querySelector('kai-menu');
  menu.items = [
    { heading: true, label: 'Actions' },
    { id: 'add-files', label: 'Add files or photos', icon: 'paperclip', shortcut: '⌘U' },
    { id: 'add-github', label: 'Add from GitHub', icon: 'github' },
    { separator: true },
    { id: 'web-search', label: 'Web search', icon: 'globe', checked: true },
  ];

  menu.addEventListener('kai-select', (e) => {
    console.log(e.detail); // { id } — or { id, checked } for a checkbox item
  });
</script>
```

## Examples

### The "+" menu

Headings group the list, a submenu nests deeper actions, a separator splits sections, and a checkbox tracks a toggle. This is the composer add-content menu.

### Row overflow

A flat set of actions behind a `⋯` button — the default trigger when you set neither `trigger-icon` nor `trigger-label`.

### Select-style trigger

Pair `trigger-label` with `trigger-icon-trailing="chevron-down"` for a control that reads like a select — current value on the left, chevron on the right.

## Slots

The menu builds its own trigger from the `trigger-*` props. Slot your own element when you need full control of it:

```html
<kai-menu>
  <button slot="trigger" aria-label="Open menu">+</button>
</kai-menu>
```

## Props

## Events

## Composed from