# Using ox_lib with ESX Legacy (/docs/guides/ox-lib)

**`ox_lib` can be used alongside ESX Legacy**, providing notifications, progress indicators, context menus, callbacks and other reusable client-side utilities. It does not replace the official ESX `esx_lib` resource.

## Install ox_lib alongside ESX [#install-ox_lib-alongside-esx]

Download a maintained release from [Community Ox](https://github.com/communityox/ox_lib) or the appropriate maintained repository for your installation. The library must be built and include its web assets.

```bash title="server.cfg"
ensure oxmysql
ensure ox_lib
ensure esx_lib
ensure es_extended
ensure my_resource
```

Add the initialization script before your own resource files:

```lua title="fxmanifest.lua"
fx_version 'cerulean'
game 'gta5'

shared_scripts {
    '@ox_lib/init.lua',
    '@es_extended/imports.lua',
}

client_script 'client.lua'
server_script 'server.lua'
dependencies { 'ox_lib', 'es_extended' }
```

Use `lib` for ox_lib APIs and `ESX` for ESX APIs. They are separate global objects supplied by their respective imports.

## Notifications from client and server [#notifications-from-client-and-server]

On the **client**:

```lua title="client.lua"
lib.notify({
    title = 'Delivery completed',
    description = 'Your package was delivered.',
    type = 'success',
    duration = 3500,
})
```

On the **server**, target a specific player:

```lua title="server.lua"
RegisterCommand('testnotify', function(source)
    if source == 0 then return end

    TriggerClientEvent('ox_lib:notify', source, {
        title = 'Test notification',
        description = 'ox_lib is available on your client.',
        type = 'inform',
    })
end, false)
```

Don't accidentally send a client-only notification to all players. The normal ESX equivalents, `ESX.ShowNotification` on the client and `xPlayer.showNotification` on the server, are also valid without ox_lib.

## Progress bars and cancellation [#progress-bars-and-cancellation]

The following **client-side** call returns `true` on successful completion and `false` when cancelled. Treat it as a user interface action, not proof that the player earned an item.

```lua title="client.lua"
RegisterCommand('testprogress', function()
    local completed = lib.progressBar({
        duration = 3000,
        label = 'Preparing package',
        canCancel = true,
        useWhileDead = false,
        disable = {
            move = true,
            car = true,
            combat = true,
        },
    })

    if completed then
        lib.notify({ description = 'Animation finished', type = 'success' })
    else
        lib.notify({ description = 'Cancelled', type = 'warning' })
    end
end, false)
```

`lib.progressCircle` accepts comparable options and presents a circular indicator. **Any money, item or job change must be independently authorized by the server.**

## Context menus and callbacks [#context-menus-and-callbacks]

For context menus use `lib.registerContext` and `lib.showContext`. For asynchronous client/server interactions, consult the ox_lib callback module. These APIs have different signatures from the native ESX menu and callback APIs, so do not mix their function names.

Use the [ox_lib documentation](https://github.com/communityox/docs/tree/main/pages/ox_lib) for the exact API signatures. If an existing ESX addon already uses `esx_context` or `esx_progressbar`, you do not have to replace it just to use ox_lib in a different script.

## Troubleshooting [#troubleshooting]

| Error | Fix |
| --- | --- |
| `attempt to index a nil value (global 'lib')` | Import `@ox_lib/init.lua` before your scripts |
| `No such export` from ox_lib | Check installation, build assets and startup |
| Notification works in client but not server | Use `TriggerClientEvent('ox_lib:notify', source, data)` |
| `lib.progressBar` always cancels | Review player state and your cancellation/disable options |
| ESX functions are nil | Import `@es_extended/imports.lua` separately |

## Related [#related]

- [ESX client UI functions](/docs/es_extended/client/ui)
- [ESX notification resource](/docs/core/esx_notify)
- [ESX progressbar resource](/docs/core/esx_progressbar)
- [ox_target with ESX](/docs/guides/ox-target)