# Menu

```ts
import { Menu, Submenu, MenuItem, MenuSpacer } from 'cx/widgets';
```



The `Menu` widget displays a list of options or commands in horizontal or vertical form. Use `Submenu` to create nested menus, and `MenuItem` for individual actions.

Menus are focus-driven — when focus leaves the menu, all submenus close automatically. To programmatically close a menu, call `document.activeElement.blur()`.

## Horizontal Menu

```tsx
import { Menu, Submenu, MenuItem } from "cx/widgets";

export default (
  <Menu horizontal>
    <Submenu>
      File
      <Menu putInto="dropdown">
        <MenuItem autoClose onClick={() => alert("New")}>
          New
        </MenuItem>
        <MenuItem autoClose onClick={() => alert("Open")}>
          Open
        </MenuItem>
        <MenuItem autoClose onClick={() => alert("Save")}>
          Save
        </MenuItem>
        <hr />
        <MenuItem disabled>Export (disabled)</MenuItem>
      </Menu>
    </Submenu>
    <Submenu>
      Edit
      <Menu putInto="dropdown">
        <MenuItem autoClose onClick={() => {}}>Cut</MenuItem>
        <MenuItem autoClose onClick={() => {}}>Copy</MenuItem>
        <MenuItem autoClose onClick={() => {}}>Paste</MenuItem>
      </Menu>
    </Submenu>
    <Submenu>
      View
      <Menu putInto="dropdown">
        <MenuItem autoClose onClick={() => {}}>Zoom In</MenuItem>
        <MenuItem autoClose onClick={() => {}}>Zoom Out</MenuItem>
        <Submenu arrow>
          More Options
          <Menu putInto="dropdown">
            <MenuItem autoClose onClick={() => {}}>Option 1</MenuItem>
            <MenuItem autoClose onClick={() => {}}>Option 2</MenuItem>
          </Menu>
        </Submenu>
      </Menu>
    </Submenu>
  </Menu>
);

```

Use the `horizontal` prop on `Menu` to create a horizontal menu bar. Submenus are defined by nesting a `Menu` with `putInto="dropdown"` inside a `Submenu`. Add `arrow` to submenus to show an expansion indicator.

## Vertical Menu

```tsx
import { Menu, Submenu, MenuItem } from "cx/widgets";

export default (
  <Menu style={{ width: "200px" }}>
    <MenuItem autoClose onClick={() => alert("Dashboard")}>
      Dashboard
    </MenuItem>
    <MenuItem autoClose onClick={() => alert("Reports")}>
      Reports
    </MenuItem>
    <Submenu arrow>
      Settings
      <Menu putInto="dropdown">
        <MenuItem autoClose onClick={() => {}}>Profile</MenuItem>
        <MenuItem autoClose onClick={() => {}}>Preferences</MenuItem>
        <MenuItem autoClose onClick={() => {}}>Security</MenuItem>
      </Menu>
    </Submenu>
    <hr />
    <MenuItem autoClose onClick={() => alert("Logout")}>
      Logout
    </MenuItem>
  </Menu>
);

```

Vertical menus are the default orientation. They work well for sidebar navigation or context menus.

## Icons and Checkboxes

```tsx
import { createModel } from "cx/data";
import { Menu, MenuItem } from "cx/widgets";
import "../../icons/lucide";

interface PageModel {
  darkMode: boolean;
  notifications: boolean;
  autoSave: boolean;
}

const m = createModel<PageModel>();

export default (
  <Menu icons style={{ width: "200px" }}>
    <MenuItem icon="search" autoClose onClick={() => alert("Search")}>
      Search
    </MenuItem>
    <MenuItem icon="folder" autoClose onClick={() => alert("Browse")}>
      Browse Files
    </MenuItem>
    <hr />
    <MenuItem checked={m.darkMode}>Dark Mode</MenuItem>
    <MenuItem checked={m.notifications}>Notifications</MenuItem>
    <MenuItem checked={m.autoSave}>Auto Save</MenuItem>
  </Menu>
);

```

Add `icons` to `Menu` to reserve space for icons. Use `icon` on `MenuItem` for action icons, or `checked` with a binding to create checkbox items.

## Overflow

```tsx
import { Menu, Submenu, MenuItem, MenuSpacer } from "cx/widgets";

export default (
  <Menu horizontal overflow style={{ width: "300px" }}>
    <Submenu>
      File
      <Menu putInto="dropdown">
        <MenuItem autoClose onClick={() => {}}>New</MenuItem>
        <MenuItem autoClose onClick={() => {}}>Open</MenuItem>
        <MenuItem autoClose onClick={() => {}}>Save</MenuItem>
      </Menu>
    </Submenu>
    <Submenu>
      Edit
      <Menu putInto="dropdown">
        <MenuItem autoClose onClick={() => {}}>Cut</MenuItem>
        <MenuItem autoClose onClick={() => {}}>Copy</MenuItem>
        <MenuItem autoClose onClick={() => {}}>Paste</MenuItem>
      </Menu>
    </Submenu>
    <Submenu>
      View
      <Menu putInto="dropdown">
        <MenuItem autoClose onClick={() => {}}>Zoom In</MenuItem>
        <MenuItem autoClose onClick={() => {}}>Zoom Out</MenuItem>
      </Menu>
    </Submenu>
    <MenuSpacer />
    <Submenu>
      Help
      <Menu putInto="dropdown">
        <MenuItem autoClose onClick={() => {}}>Documentation</MenuItem>
        <MenuItem autoClose onClick={() => {}}>About</MenuItem>
      </Menu>
    </Submenu>
  </Menu>
);

```

Set `overflow` on horizontal menus to automatically move items that don't fit into an overflow submenu. Use `MenuSpacer` to push items to the right side.

## Menu Configuration

| Property | Type | Description |
| -------- | ---- | ----------- |
| `horizontal` | `boolean` | Set to `true` for horizontal menus. Default is `false`. |
| `itemPadding` | `string` | Size of menu items: `xsmall`, `small`, `medium`, `large`, `xlarge`. Default is `small` for horizontal, `medium` for vertical. |
| `icons` | `boolean` | Reserve space for icons in menu items. Default is `false`. |
| `overflow` | `boolean` | Enable overflow menu for items that don't fit. Horizontal menus only. |
| `overflowIcon` | `string` | Icon for the overflow menu button. |
| `autoFocus` | `boolean` | Auto-focus first menu item on mount. |

## MenuItem Configuration

| Property | Type | Description |
| -------- | ---- | ----------- |
| `autoClose` | `boolean` | Close the menu when this item is clicked. |
| `icon` | `StringProp` | Icon to display before the item text. |
| `checked` | `BooleanProp` | Bind to create a checkbox menu item. |
| `disabled` | `BooleanProp` | Disable the menu item. |
| `arrow` | `BooleanProp` | Show an arrow indicating a submenu. |
| `onClick` | `function` | Handler called when the item is clicked. |
| `tooltip` | `string \| object` | Tooltip configuration. |
| `keyboardShortcut` | `KeyCode` | Register a keyboard shortcut for this item. |
| `openOnFocus` | `boolean` | Open dropdown when focused. Default is `true`. |
| `hoverToOpen` | `boolean` | Open submenu on hover instead of focus. |
| `clickToOpen` | `boolean` | Require click to open submenu instead of hover. |
| `placement` | `string` | Dropdown placement: `up`, `down`, `left`, `right`, or corners like `down-right`. |
| `confirm` | `string \| object` | Show confirmation dialog before executing onClick. |