PiTyUs.Hire me

Frameworks

Getting started with ox_lib

A practical ox_lib guide for FiveM developers: installing and importing it, cache, callbacks, notifications, progress bars, context menus, input dialogs, text UI, points and zones, lib.addCommand with ACE restrictions, keybinds and locale convars — with copy-paste examples.

Updated 14 min readBy PiTyUs · FiveM developer

Overview

ox_lib by Overextended is the standard utility library of modern FiveM servers: callbacks, notifications, progress bars, menus, input dialogs, zones, commands and a cache of common values, usable from any framework. Learning it saves you from writing — and debugging — the same helpers in every script.

01Installing and importing

  1. Download the latest release build of ox_lib from Overextended’s GitHub releases (not the source code zip — the release contains the built UI).
  2. Place it in resources and add ensure ox_lib to server.cfg above your frameworks and scripts.
  3. In each resource that uses it, import it in the fxmanifest.
fxmanifest.lualua
fx_version 'cerulean'
game 'gta5'
lua54 'yes'

shared_script '@ox_lib/init.lua'
client_script 'client.lua'
server_script 'server.lua'

dependency 'ox_lib'
server.cfg — optional settingscfg
setr ox:locale en
setr ox:primaryColor blue
setr ox:primaryShade 8

cache

ox_lib keeps frequently used values up to date so you do not call natives every frame: cache.ped, cache.playerId, cache.serverId, cache.vehicle (or false), cache.seat, cache.weapon (or false), plus cache.resource. React to changes with lib.onCache.

client.lualua
lib.onCache('vehicle', function(vehicle)
    if vehicle then
        print('entered', GetDisplayNameFromVehicleModel(GetEntityModel(vehicle)))
    end
end)

Callbacks

server.lualua
lib.callback.register('bank:getBalance', function(source)
    local player = exports.qbx_core:GetPlayer(source) -- or your framework
    return player and player.PlayerData.money.bank or 0
end)
client.lualua
local balance = lib.callback.await('bank:getBalance', false)
lib.notify({ title = 'Bank', description = ('Balance: $%d'):format(balance), type = 'inform' })

The second argument of lib.callback.await is a client-side rate limit in milliseconds (false for none). Callbacks are requests like events — validate inside them. More in callbacks explained.

Notifications, progress and dialogs

client.lualua
lib.notify({ title = 'Garage', description = 'Vehicle stored', type = 'success' })

if lib.progressBar({
    duration = 5000,
    label = 'Repairing engine',
    useWhileDead = false,
    canCancel = true,
    disable = { car = true, move = true, combat = true },
    anim = { dict = 'mini@repair', clip = 'fixing_a_player' },
}) then
    print('finished')
else
    print('cancelled')
end

local input = lib.inputDialog('Transfer', {
    { type = 'number', label = 'Player ID', required = true },
    { type = 'number', label = 'Amount', required = true, min = 1 },
})
if input then
    TriggerServerEvent('bank:transfer', input[1], input[2])
end
FunctionShows
lib.notifyToast notification (success, error, warning, inform)
lib.progressBar / lib.progressCircleTimed action; returns true if completed
lib.inputDialogForm; returns an array of values or nil
lib.alertDialogConfirm dialog; returns 'confirm' or 'cancel'
lib.showTextUI / lib.hideTextUIPersistent hint such as “[E] Open”
lib.registerContext / lib.showContextContext menus
lib.registerMenu / lib.showMenuKeyboard-driven list menus

Context menus

client.lualua
lib.registerContext({
    id = 'garage_menu',
    title = 'Garage',
    options = {
        { title = 'Take out vehicle', icon = 'car', onSelect = function() TriggerServerEvent('garage:takeOut') end },
        { title = 'Store vehicle', icon = 'warehouse', serverEvent = 'garage:store' },
        { title = 'Locked option', disabled = true },
    },
})

lib.showContext('garage_menu')

Points and zones

client.lualua
local point = lib.points.new({
    coords = vec3(215.8, -810.1, 30.7),
    distance = 3.0,
    onEnter = function() lib.showTextUI('[E] Open garage') end,
    onExit = function() lib.hideTextUI() end,
    nearby = function()
        if IsControlJustReleased(0, 38) then lib.showContext('garage_menu') end
    end,
})

lib.zones.box({
    coords = vec3(441.0, -982.0, 30.7),
    size = vec3(6.0, 6.0, 3.0),
    rotation = 0.0,
    debug = false,
    onEnter = function() lib.notify({ description = 'Entered Mission Row' }) end,
})

nearby only runs while the player is inside the distance, so the idle cost stays near zero. Zones in depth: zones with ox_lib.

Commands and keybinds

server.lualua
lib.addCommand('givecash', {
    help = 'Give cash to a player',
    params = {
        { name = 'target', type = 'playerId', help = 'Server ID' },
        { name = 'amount', type = 'number', help = 'Amount' },
    },
    restricted = 'group.admin',
}, function(source, args)
    -- args.target and args.amount are already parsed
end)

restricted accepts an ACE principal such as group.admin (or a list); ox_lib adds the ACE for the command. On the client, lib.addKeybind wraps key mapping so players can rebind keys in the settings — see commands and key mapping.

Frequently asked questions

How do I use ox_lib in my script?

Add shared_script '@ox_lib/init.lua' and lua54 'yes' to the fxmanifest and start ox_lib before your resource.

Why is lib nil in my script?

The import is missing from the fxmanifest, ox_lib is not started before your resource, or you downloaded the source instead of a release build.

Is ox_lib framework-specific?

No. It works with ESX, QBCore, Qbox, ox_core and standalone scripts.

How do I change the ox_lib language?

Set setr ox:locale <code> in server.cfg, for example setr ox:locale de.

What does the second argument of lib.callback.await do?

It is a client-side rate limit (delay in ms) between calls; pass false for none.

Need this built, not just explained?

Ten years of FiveM work, from Lua to NUI

Custom resources, React NUI, ESX / QBCore / Qbox integration, OneSync performance audits and security reviews — plus the websites and SEO around your server brand.

Talk on DiscordSee services

Related guides

All FiveM guides