# qb-menu

`qb-menu` renders a Lua array as an action menu. This reference is pinned to `d82abeeb`; its implementation is `client.lua`, not `client/main.lua`. The tutorial uses QBCore `9b3cddcc` and deliberately keeps authorization on the server.

## Exports

| Client export | Arguments and behavior |
| --- | --- |
| `openMenu(data, sort, skipFirst)` | Non-empty array of menu entries; optional sorting by `header`; `skipFirst` preserves the first entry during sorting |
| `closeMenu()` | Clear the current menu and release its focus |
| `showHeader(data)` | Render a header view; it is not equivalent to calling `openMenu` with focus |

Build a fresh array when opening a dynamic menu. The pinned implementation sorts the supplied table and may resolve item icons in its entries; do not reuse a shared mutable array as your application state.

```lua
exports['qb-menu']:openMenu({
    { header = 'Garage', isMenuHeader = true },
    {
        header = 'Store vehicle',
        txt = 'Request storage through your garage resource',
        params = { event = 'mygarage:client:store' }
    }
})
```

This is a schema example: `mygarage:client:store` must be implemented by your resource. It does not create garage storage by itself.

## Menu entries and argument passing

| Field | Use |
| --- | --- |
| `header`, `txt`, `icon` | Display text and optional icon |
| `isMenuHeader` | Non-action heading |
| `disabled` | Presentation-level disabled state, not permission enforcement |
| `params.event` | Event or command name; a function when using `isAction` |
| `params.args` | One payload passed to the handler, commonly a table |
| `params.isServer` | Dispatch with `TriggerServerEvent` |
| `params.isCommand` | Execute the command string in `params.event` |
| `params.isQBCommand` | Dispatch through the QBCore command path |
| `params.isAction` | Call the function in `params.event` with `params.args` |

With none of the dispatch flags, the implementation calls a local client event. Set only the dispatch mode you intend. A top-level `action` function takes precedence over the `params` dispatch path and is invoked without the argument payload.

## Complete example: dynamic duty menu and submenu

Create `resources/[custom]/docs_menu/` with `fxmanifest.lua`, `client.lua` and `server.lua`. The example allows a police officer at a configured counter to request a duty change. Replace the sample counter coordinates on the server with a location in your map.

`fxmanifest.lua`:

```lua
fx_version 'cerulean'
game 'gta5'

dependencies { 'qb-core', 'qb-menu' }
client_script 'client.lua'
server_script 'server.lua'
```

Keep `ensure docs_menu` after `qb-core` and `qb-menu`. The server position check below requires a working OneSync server context.

`client.lua`:

```lua
local QBCore = exports['qb-core']:GetCoreObject()

local function openRoot()
    local data = QBCore.Functions.GetPlayerData()
    local job = data.job or {}
    exports['qb-menu']:openMenu({
        { header = 'Training desk', isMenuHeader = true },
        {
            header = 'Duty settings',
            txt = job.onduty and 'Currently on duty' or 'Currently off duty',
            disabled = job.name ~= 'police',
            params = {
                event = 'docs_menu:client:submenu',
                args = { page = 'duty' }
            }
        },
        { header = 'Close', params = { event = 'docs_menu:client:close' } }
    })
end

AddEventHandler('docs_menu:client:submenu', function(args)
    if type(args) ~= 'table' or args.page ~= 'duty' then return end
    local data = QBCore.Functions.GetPlayerData()
    local job = data.job or {}
    if job.name ~= 'police' then return end
    local desired = job.onduty ~= true

    exports['qb-menu']:openMenu({
        { header = 'Duty settings', isMenuHeader = true },
        {
            header = desired and 'Go on duty' or 'Go off duty',
            txt = 'The server checks your job and counter location.',
            params = {
                event = 'docs_menu:server:setDuty',
                isServer = true,
                args = { desired = desired }
            }
        },
        { header = 'Back', params = { event = 'docs_menu:client:root' } }
    })
end)

AddEventHandler('docs_menu:client:root', openRoot)
AddEventHandler('docs_menu:client:close', function()
    exports['qb-menu']:closeMenu()
end)

RegisterCommand('docs_menu', openRoot, false)

AddEventHandler('onResourceStop', function(resource)
    if resource ~= GetCurrentResourceName() then return end
    if GetResourceState('qb-menu') == 'started' then
        exports['qb-menu']:closeMenu()
    end
end)
```

Run `/docs_menu` in chat or `docs_menu` in F8. The root and submenu re-read current job data each time, so the entry is not permanently cached at resource startup. The back button opens the root handler rather than constructing an unrelated second menu.

## Server-side authorization

`server.lua`:

```lua
local QBCore = exports['qb-core']:GetCoreObject()
local counter = vector3(441.2, -981.9, 30.7)
local nextRequest = {}

RegisterNetEvent('docs_menu:server:setDuty', function(args)
    local src = source
    if type(args) ~= 'table' or type(args.desired) ~= 'boolean' then return end
    local now = os.time()
    if (nextRequest[src] or 0) > now then return end
    nextRequest[src] = now + 2

    local player = QBCore.Functions.GetPlayer(src)
    if not player then return end
    local job = player.PlayerData.job
    if not job or job.name ~= 'police' then return end

    local ped = GetPlayerPed(src)
    if ped == 0 or not DoesEntityExist(ped) then return end
    if GetPlayerRoutingBucket(src) ~= 0 then return end
    if #(GetEntityCoords(ped) - counter) > 3.0 then
        TriggerClientEvent('QBCore:Notify', src, 'Go to the training counter first.', 'error')
        return
    end

    player.Functions.SetJobDuty(args.desired)
    TriggerClientEvent('QBCore:Notify', src, 'Duty updated. Reopen the menu to check it.', 'success')
end)

AddEventHandler('playerDropped', function()
    nextRequest[source] = nil
end)
```

The client provides a requested boolean, not a job, grade, player ID or authorization decision. The server resolves `source`, checks its own player data, rate-limits requests and verifies distance and routing bucket. A disabled button is not a substitute for these checks.

This is a teaching resource, not a replacement for your existing duty system. When integrating into a server with duty logging or additional restrictions, call its authorized workflow instead of maintaining two competing duty implementations. For economy actions, also validate server-owned prices, quantities, inventory capacity and failure recovery; do not repurpose this boolean handler into a generic money event.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Menu does not open | `qb-menu` started successfully; the calling code is client-side; `data` is a non-empty array |
| Menu opens, click fails | Every actionable entry has a valid `params` table or a top-level `action` |
| Handler receives nil arguments | `args` belongs inside `params`; the handler receives one payload, not automatically unpacked positional fields |
| Server handler never runs | `isServer = true`, exact event name and a loaded `server.lua` |
| Back button opens stale content | Rebuild entries from player data inside the root handler |
| Click rejected at the counter | Actual coordinates, height, job and routing bucket; retain the server checks |
| Cursor remains after closing | Use `closeMenu`; inspect errors before changing focus in unrelated resources |
| `No such export GetShared` during menu startup | Caller/core version mismatch; compare the pinned menu's first line with the deployed core exports |

## Manual acceptance checks

Source review is not an executed FiveM test. On staging, verify: root → submenu → back; on-duty/off-duty labels after reopening; a valid request at the counter; a denied request from far away or the wrong job; malformed payload rejection; rapid-click throttling; resource-stop cleanup; and reconnect behavior with your server's duty defaults.

## Sources

- [qb-menu client implementation, d82abeeb](https://github.com/qbcore-fivem/qb-menu/blob/d82abeeb758a0c7b48622dc5b6831dcd0ecd82c8/client.lua).
- [qb-menu README and manifest](https://github.com/qbcore-fivem/qb-menu/tree/d82abeeb758a0c7b48622dc5b6831dcd0ecd82c8).
- [Core player methods and compatibility wrappers, 9b3cddcc](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/player.lua).
- [Safe server events](/docs/security/safe-server-events) and [OneSync](/docs/advanced/onesync).
