ox_lib Complete Guide: The Essential FiveM Utility Library

ox_lib is the most important utility library in the FiveM ecosystem. It provides the foundation that modern scripts, frameworks, and UI systems are built on. Whether you're running ESX, QBCore, or QBOX, understanding ox_lib is essential for server development in 2026.

What is ox_lib?

ox_lib is an open-source utility library developed by the Overextended team. It provides shared functions, UI components, and developer tools that other resources depend on. Think of it as the standard library for FiveM development.

It's not a framework itself -- it works alongside your framework (ESX, QBCore, or QBOX) to provide common functionality that would otherwise need to be reimplemented in every script.

Core Features

UI Components

ox_lib includes a complete set of UI elements that scripts can use without bundling their own interfaces:

• Context menus: Configurable menus with icons, descriptions, and nested submenus
• Notifications: Toast-style notifications with types (success, error, warning, info)
• Progress bars: Linear and circular progress indicators with cancellation support
• Input dialogs: Forms with text fields, checkboxes, selects, color pickers, date pickers
• Text UI: Simple key-prompt displays for interaction hints
• Skill checks: Timing-based minigames for actions like lockpicking or hacking
• Radial menu: Circular menu for quick-access actions

These UI components give servers a consistent look and feel across all scripts that use ox_lib, instead of every resource having its own mismatched UI.

Shared Modules

Modules that both client and server scripts can import:

• Locale: Internationalization support for multi-language servers
• Logger: Structured logging with configurable levels
• Table utilities: Deep copy, merge, contains, and other table operations
• Math utilities: Rounding, clamping, scaling, and group math functions
• String utilities: Formatting, trimming, and pattern matching helpers

Client Utilities

• Zones: Poly and sphere zone creation for triggering events when players enter/exit areas
• Points: Efficient distance-based point detection (lighter than zones for simple checks)
• Raycast: Camera-based raycasting for targeting entities and surfaces
• Streaming: Request and load models, animations, and particle effects with automatic cleanup
• Vehicle properties: Get/set complete vehicle state (mods, colors, damage, extras)

Server Utilities

• Version checker: Automatic update notifications for resource developers
• Callbacks: Client-server callback system (similar to ESX/QBCore callbacks but cleaner)
• Access control: ACE-based permission checks

Installation

ox_lib is straightforward to install:

1. Download the latest release from the GitHub repository
2. Place it in your resources folder
3. Add ensure ox_lib to your server.cfg before any resource that depends on it
4. Run refresh and ensure ox_lib in the server console

Important: ox_lib must start before any resource that uses it. Place the ensure line near the top of your server.cfg, right after your framework.

How Scripts Use ox_lib

When a script says it requires ox_lib, it means the script uses ox_lib's functions instead of implementing its own. For example:

• A job script might use ox_lib's progress bar for work actions
• A police script might use ox_lib's input dialogs for writing reports
• A drug script might use ox_lib's skill checks for processing
• A inventory system might use ox_lib's context menus for item actions

This is why ox_lib has become standard: it eliminates duplicated effort and gives players a consistent interface.

ox_lib and the OX Ecosystem

ox_lib is the foundation of a larger ecosystem of resources from the Overextended team:

Resource	Purpose	Depends on ox_lib?
ox_inventory	Inventory system	Yes
ox_target	Interaction/targeting	Yes
ox_doorlock	Door management	Yes
ox_fuel	Fuel system	Yes
ox_core	Framework (QBOX base)	Yes
ox_mdt	Police MDT/CAD	Yes

QBOX servers get the deepest integration since QBOX is built on ox_core, which itself depends on ox_lib. Everything works together natively.

Common Issues and Solutions

Scripts failing to start

If scripts error with "ox_lib not found" or similar messages, ensure ox_lib starts before them in your server.cfg. Resource load order matters.

UI not appearing

Clear your FiveM cache (%localappdata%/FiveM/FiveM.app/data/cache). NUI cache can prevent updated UI from loading. See our troubleshooting guide for more cache fixes.

Version conflicts

Keep ox_lib updated. Older versions may lack functions that newer scripts require. Check the script's documentation for minimum ox_lib version requirements.

Performance concerns

ox_lib itself is lightweight. If you see high resource usage, the problem is likely in scripts using ox_lib, not ox_lib itself. Use resmon to identify the actual bottleneck.

ox_lib vs Alternatives

Before ox_lib became standard, servers used various alternatives:

• qb-menu / qb-input: QBCore's built-in UI components. Still functional but less feature-rich. ox_lib's equivalents are faster and more flexible.
• ESX menus: Legacy ESX UI system. Significantly outdated. ox_lib is the recommended replacement for ESX servers too.
• Custom NUI: Some premium scripts bundle their own UI. This works but leads to inconsistent player experiences across different scripts.

The ecosystem has converged on ox_lib because it's free, well-maintained, and provides a consistent foundation for everyone.

FAQ

Is ox_lib required for my server?

Technically no, but practically yes. Most modern scripts depend on it. Not using ox_lib severely limits which resources you can install.

Does ox_lib affect server performance?

Minimally. ox_lib is one of the lightest utility libraries available. Its resource footprint is typically under 0.01ms idle. The UI components only consume resources when actively displayed.

Can I use ox_lib with ESX?

Yes. ox_lib is framework-agnostic. It works with ESX, QBCore, QBOX, and standalone servers. This is one of its key strengths.

How often should I update ox_lib?

Check for updates monthly. Major updates can add new features that scripts may require. Always test updates on a staging server first before pushing to production.

Developer Quick Reference: Most-Used ox_lib Functions

If you're writing scripts or customizing existing ones, here are the most commonly used ox_lib functions with practical examples. The full documentation is available at overextended.dev/ox_lib and the source code on GitHub.

Notifications

-- Client-side notification
lib.notify({
    title = 'Police',
    description = 'You have been fined $500 for speeding.',
    type = 'error',  -- 'success' | 'error' | 'warning' | 'inform'
    duration = 5000,
    position = 'top-right'
})

Notifications are the most common ox_lib function you'll encounter. Every script that needs to tell the player something uses this pattern. The type field controls the color and icon automatically.

Progress Bars

-- Client-side progress bar with cancellation
local completed = lib.progressBar({
    duration = 5000,
    label = 'Picking lock...',
    useWhileDead = false,
    canCancel = true,
    disable = {
        car = true,
        move = true,
        combat = true
    },
    anim = {
        dict = 'anim@amb@clubhouse@tutorial@bkr_tut_ig3@',
        clip = 'machinic_loop_mechandplayer'
    }
})

if completed then
    -- Action succeeded
else
    -- Player cancelled
end

The disable table controls what the player can't do during the action. The anim table plays a GTA animation simultaneously. Most minigame scripts use this exact pattern.

Context Menus

-- Open a context menu
lib.registerContext({
    id = 'mechanic_menu',
    title = 'Mechanic Services',
    options = {
        {
            title = 'Repair Vehicle',
            description = 'Full vehicle repair - $500',
            icon = 'wrench',
            onSelect = function()
                -- Handle repair
            end
        },
        {
            title = 'Performance Tuning',
            description = 'Upgrade engine and suspension',
            icon = 'gauge-high',
            arrow = true,  -- shows arrow indicating submenu
            menu = 'tuning_menu'
        }
    }
})

lib.showContext('mechanic_menu')

Context menus support icons (FontAwesome names), submenus via menu chaining, metadata display, and conditional option visibility. They're the standard interaction menu for most modern FiveM scripts.

Input Dialogs

-- Collect player input
local input = lib.inputDialog('Fine Player', {
    { type = 'input', label = 'Reason', required = true, max = 100 },
    { type = 'number', label = 'Amount ($)', min = 1, max = 10000 },
    { type = 'checkbox', label = 'Add to criminal record', checked = true }
})

if input then
    local reason = input[1]
    local amount = input[2]
    local addToRecord = input[3]
    -- Process fine
end

Input dialogs replace the old qb-input and ESX input systems. They support text, numbers, selects, checkboxes, color pickers, and date/time pickers all in one modal.

Skill Checks (Minigames)

-- Simple skill check
local success = lib.skillCheck({'easy', 'easy', 'medium'}, {'w', 'a', 's', 'd'})

-- Custom difficulty
local success = lib.skillCheck(
    {
        { areaSize = 35, speedMultiplier = 1 },   -- easy
        { areaSize = 25, speedMultiplier = 1.5 }, -- medium
    },
    {'w', 'a', 's', 'd'}
)

if success then
    -- Player passed the check
end

Skill checks are timing-based minigames where a zone rotates around a circle and the player must press the key when the indicator enters the target area. Used extensively for lockpicking, hacking, drug processing, and other skill-based actions. The areaSize controls how large the target zone is (bigger = easier), and speedMultiplier controls rotation speed.

Zones and Points

-- Create an interaction zone
local zone = lib.zones.sphere({
    coords = vec3(452.0, -980.0, 30.0),
    radius = 5.0,
    debug = false,
    onEnter = function()
        lib.showTextUI('[E] Access ATM')
    end,
    onExit = function()
        lib.hideTextUI()
    end,
    inside = function()
        if IsControlJustReleased(0, 38) then -- E key
            -- Open ATM menu
        end
    end
})

-- Create a lightweight distance point (cheaper than zones)
local point = lib.points.new({
    coords = vec3(452.0, -980.0, 30.0),
    distance = 10.0,
    onEnter = function(self)
        -- Within 10 units
    end,
    onExit = function(self)
        -- Left the area
    end,
    nearby = function(self)
        -- Called every frame while inside
    end
})

Use zones when you need precise shape detection (poly zones for oddly shaped areas). Use points when you just need radius-based detection — they're significantly cheaper CPU-wise for large numbers of locations.

Callbacks (Client ↔ Server)

-- Server-side: register callback
lib.callback.register('myresource:getData', function(source, param1)
    local player = exports.qbx_core:GetPlayer(source)
    return player.PlayerData.money.cash
end)

-- Client-side: call server callback
local cash = lib.callback.await('myresource:getData', false, 'someParam')
print('Player cash: ' .. cash)

-- Async version with callback function
lib.callback('myresource:getData', false, function(result)
    print('Got result: ' .. result)
end, 'someParam')

ox_lib callbacks replace the older QBCore.Functions.TriggerCallback and ESX callback patterns. They support both async/await style and traditional callback functions, and handle timeout and error cases automatically.

Version History and What Changed

Understanding what version introduced key features helps when debugging compatibility issues:

Version	Key Features Added
3.x	Radial menu, zones rewrite, improved NUI performance, skill check overhaul
2.x	Input dialogs, context menu improvements, callback system, points system
1.x	Initial release: notifications, progress bars, basic context menus, streaming utilities

Always check the GitHub releases page for the current version changelog. Scripts often specify a minimum ox_lib version in their fxmanifest.lua:

dependencies {
    '/server:7290',
    '/onesync',
    'ox_lib >= 3.0.0'
}

If a script errors with "function not found" after updating ox_lib, check whether you actually updated to the version it requires, or if the script needs the older API that was changed.

Using ox_lib with QBOX

The deepest integration is with QBOX servers. Since QBOX is built on ox_core (which depends on ox_lib), the library is already initialized before any other resource starts. You get:

• Zero configuration: ox_lib auto-initializes as part of the framework startup
• Guaranteed version compatibility: QBOX pins to a tested ox_lib version
• Native callbacks: The QBOX callback system uses ox_lib under the hood
• Consistent UI: All QBOX-native scripts share the same ox_lib UI theme

If you're migrating from QBCore to QBOX, read the QBCore to QBOX migration guide — ox_lib compatibility is one of the smoothest parts of that transition. And for choosing the right inventory system that pairs with ox_lib, see our best FiveM inventory scripts guide.

For the full framework comparison showing how ox_lib fits into each ecosystem, read our ESX vs QBCore vs QBOX technical comparison.

For more script recommendations and server setup guides, see our complete FiveM scripts guide or browse our marketplace.