QBCore Frameworkqbcore.netCommunity docs
On this page

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 exportArguments 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.

FieldUse
header, txt, iconDisplay text and optional icon
isMenuHeaderNon-action heading
disabledPresentation-level disabled state, not permission enforcement
params.eventEvent or command name; a function when using isAction
params.argsOne payload passed to the handler, commonly a table
params.isServerDispatch with TriggerServerEvent
params.isCommandExecute the command string in params.event
params.isQBCommandDispatch through the QBCore command path
params.isActionCall 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

SymptomCheck
Menu does not openqb-menu started successfully; the calling code is client-side; data is a non-empty array
Menu opens, click failsEvery actionable entry has a valid params table or a top-level action
Handler receives nil argumentsargs belongs inside params; the handler receives one payload, not automatically unpacked positional fields
Server handler never runsisServer = true, exact event name and a loaded server.lua
Back button opens stale contentRebuild entries from player data inside the root handler
Click rejected at the counterActual coordinates, height, job and routing bucket; retain the server checks
Cursor remains after closingUse closeMenu; inspect errors before changing focus in unrelated resources
No such export GetShared during menu startupCaller/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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website