# esx_menu_list (/docs/core/esx_menu_list)

esx_menu_list renders a table menu: a header row and any number of data rows,
with buttons inside cells. Use it to show tabular data the player can act on,
such as a list of employees with "Promote" and "Fire" buttons. You open it with
`ESX.UI.Menu.Open('list', ...)`.

## Overview [#overview]

| | |
| --- | --- |
| Resource | `esx_menu_list` |
| Side | Client only |
| Menu type | `list` |
| Dependencies | `es_extended` |
| UI | jQuery + Mustache page in `html/` |

The resource has no configuration file. The menu takes mouse focus about 200 ms
after opening and releases it when the last list menu closes. If several list
menus are open, only the most recently opened one is visible.

## Opening a list menu [#opening-a-list-menu]

```lua
ESX.UI.Menu.Open('list', namespace, name, data, submit, cancel)
```

| Name | Type | Description |
| --- | --- | --- |
| `namespace` | `string` | Usually `GetCurrentResourceName()`. |
| `name` | `string` | Unique menu name inside the namespace. |
| `data` | `table` | `{ head = {...}, rows = {...} }`, see below. |
| `submit` | `function(data, menu)?` | A cell button was clicked. |
| `cancel` | `function(data, menu)?` | Escape was pressed. |

The `change` and `close` arguments of `ESX.UI.Menu.Open` are accepted, but this
menu type never sends change events. The returned `menu` object is described on
the [esx_menu_default page](/docs/core/esx_menu_default#menu-object).

### Menu data [#menu-data]

| Field | Type | Description |
| --- | --- | --- |
| `head` | `string[]` | Column headers. Escaped (shown as plain text). |
| `rows` | `table[]` | One entry per row. |
| `rows[i].cols` | `string[]` | Cell contents, one per column. Rendered as HTML. |
| `rows[i].data` | `table?` | Any data you want back when a button in this row is clicked. |

There is no `title` field; the table header is the only heading.

### Buttons in cells [#buttons-in-cells]

Inside a cell string, `{{Label|value}}` becomes a button. A cell can contain
several buttons:

```lua
cols = { 'John Doe', 'Mechanic', '{{Promote|promote}} {{Fire|fire}}' }
```

### Callback data [#callback-data]

| Field | Description |
| --- | --- |
| `data.value` | The `value` part of the clicked button. |
| `data.data` | The `data` table of the clicked row, plus `currentRow` (1-based row index). |
| `data._namespace`, `data._name` | Menu identifiers. |

`cancel` receives only `_namespace` and `_name`.

## Example [#example]

```lua title="client/main.lua"
local function openEmployeeList(employees)
    local rows = {}

    for i = 1, #employees do
        local employee = employees[i]

        rows[#rows + 1] = {
            data = { identifier = employee.identifier },
            cols = {
                employee.name,
                employee.gradeLabel,
                '{{Promote|promote}} {{Fire|fire}}',
            },
        }
    end

    ESX.UI.Menu.Open('list', GetCurrentResourceName(), 'employees', {
        head = { 'Name', 'Grade', 'Actions' },
        rows = rows,
    }, function(data, menu)
        menu.close()
        TriggerServerEvent('my_boss:employeeAction', data.data.identifier, data.value)
    end, function(data, menu)
        menu.close()
    end)
end
```

<Callout type="warn" title="Escape cell content">
`cols` are inserted as raw HTML. If a cell shows player-controlled text (names,
notes), strip `<` and `>` before you add it, or a player can inject markup into
other players' menus.
</Callout>

## Controls [#controls]

| Key | Action |
| --- | --- |
| Mouse click on a cell button | Submit |
| Escape | Cancel (on the visible menu) |

## Common issues [#common-issues]

- **Escape does nothing**: you did not pass a `cancel` callback, or it does not
  call `menu.close()`.
- **Button value has the wrong type**: jQuery reads `data-value` and converts
  numeric strings to numbers, so `{{Buy|5}}` arrives as the number `5`. Use
  string keys like `buy_5` if you need consistent types.
- **`|` or `}}` in labels breaks buttons**: the button syntax is parsed with a
  simple pattern. Keep labels free of these characters.

## Related [#related]

- [esx_menu_default](/docs/core/esx_menu_default)
- [esx_menu_dialog](/docs/core/esx_menu_dialog)
- [esx_context](/docs/core/esx_context)
- [Client UI functions](/docs/es_extended/client/ui)