# QBCore progressbar: client API and cancellation

The official `progressbar` resource provides a client-side timed UI, optional animation/props and cancel/finish handlers. This guide is pinned to [commit 6e9381d](https://github.com/qbcore-fivem/progressbar/tree/6e9381de6637bd443a8eaf1a6da0d339d8cebb15).

## Installation

Start `progressbar` before resources that call its exports. In QBCore scripts, prefer the wrapper `QBCore.Functions.Progressbar`. The client resource sets `LocalPlayer.state.inv_busy` while a progress action is running. Do not rely on an animation finishing as proof of a legitimate server-side action.

## Recommended client example

~~~lua filename="client.lua"
local QBCore = exports['qb-core']:GetCoreObject({ 'Functions' })

QBCore.Functions.Progressbar(
    'repair_vehicle',
    'Repairing vehicle',
    5000,
    false,
    true,
    {
        disableMovement = true,
        disableCarMovement = true,
        disableMouse = false,
        disableCombat = true,
    },
    { animDict = 'mini@repair', anim = 'fixing_a_player', flags = 16 },
    {}, {},
    function()
        print('Progress completed')
        -- Request a SERVER-VALIDATED action; do not award items on the client.
    end,
    function()
        print('Progress cancelled')
    end
)
~~~

Duration is in **milliseconds**. `onFinish` is not a server-side authorization decision.

## Direct client exports

[`client.lua`](https://github.com/qbcore-fivem/progressbar/blob/6e9381de6637bd443a8eaf1a6da0d339d8cebb15/client.lua) exports:

| Export | Purpose |
| --- | --- |
| `Progress(data, handler)` | Starts progress with a completion callback receiving cancellation state |
| `ProgressWithStartEvent(data, onStart, onFinish)` | Adds a start callback |
| `ProgressWithTickEvent(data, onTick, onFinish)` | Adds a per-tick callback |
| `ProgressWithStartAndTick(data, onStart, onTick, onFinish)` | Combines both |
| `isDoingSomething()` | Returns whether a progress action is active |

The source also registers client events such as `progressbar:client:cancel` and `progressbar:client:progress`; prefer the wrapper or exports over inventing a server-side progress API.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| `No such export Progress` | Caller executes on client, resource starts first |
| Progress fails while another is active | `isDoingSomething()` and overlapping UI actions |
| Animation not playing | `animDict`/`anim` and ped state |
| Action succeeds even after cancellation | Ensure the server does not trust a client completion event |
| Inventory stays busy | State cleanup after cancellation and interfering resources |

## Update checklist

1. Compare `qb-core` wrapper signature and `progressbar` client export on the deployed versions.
2. Test finish, cancel, death, reconnect and simultaneous requests.
3. Verify rewards and purchases are validated **server-side**, independent of the UI.

## Sources

[Repository](https://github.com/qbcore-fivem/progressbar/tree/6e9381de6637bd443a8eaf1a6da0d339d8cebb15) · [Client implementation](https://github.com/qbcore-fivem/progressbar/blob/6e9381de6637bd443a8eaf1a6da0d339d8cebb15/client.lua) · [Upstream usage](https://github.com/qbcore-fivem/progressbar/blob/6e9381de6637bd443a8eaf1a6da0d339d8cebb15/README.md)
