4 min read
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.
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:
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:
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:
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
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
