# Progress Bar

A progress bar with optional animation and input blocking.

***

## startProgressbar

```lua
startProgressbar(data, callback)
```

Also available as an export:

```lua
exports['koja-lib']:startProgressbar(data, callback)
```

### Parameters

| Field             | Type       | Default            | Description                                  |
| ----------------- | ---------- | ------------------ | -------------------------------------------- |
| `label`           | `string`   | `"Loading..."`     | Title text (alias: `title`)                  |
| `description`     | `string`   | `"Please wait..."` | Body text (alias: `text`)                    |
| `duration`        | `number`   | `5000`             | Duration in milliseconds (alias: `time`)     |
| `cancelable`      | `boolean`  | `false`            | Player can press X to cancel                 |
| `animation`       | `table?`   | —                  | Ped animation to play                        |
| `animation.dict`  | `string`   | —                  | Animation dictionary                         |
| `animation.name`  | `string`   | —                  | Animation name                               |
| `animation.flag`  | `number`   | `1`                | Animation flag                               |
| `inputBlock`      | `table?`   | —                  | Keys to block during the progress bar        |
| `inputBlock.keys` | `string[]` | —                  | Key names to disable (e.g. `{"E", "SPACE"}`) |

### Callback

`callback(success: boolean)` — called when the bar finishes (`true`) or is cancelled (`false`).

***

## cancelProgressbar

Cancel and hide the active progress bar immediately.

```lua
cancelProgressbar()

-- or via export:
exports['koja-lib']:cancelProgressbar()
```

***

## Theme

Appearance is controlled by `Config.UI.ProgressBar` in the config file:

```lua
Config.UI.ProgressBar = {
    theme        = "darkBlack",  -- orange | darkGray | darkBlack | navy | green | purple | red
    bottomOffset = 1,
}
```

***

## Examples

### Basic progress bar

```lua
startProgressbar({
    label    = 'Searching...',
    duration = 5000,
}, function(success)
    if not success then return end
    -- action after completion
    print('Done')
end)
```

### With animation and cancelable

```lua
startProgressbar({
    label       = 'Hotwiring',
    description = 'Hold still...',
    duration    = 8000,
    cancelable  = true,
    animation   = {
        dict = 'anim@amb@clubhouse@tutorial@bkr_tut_ig3@',
        name = 'machinic_loop_mechandplayer',
        flag = 1,
    },
    inputBlock = {
        keys = { 'SPACE', 'W', 'A', 'S', 'D' },
    },
}, function(success)
    if success then
        TriggerServerEvent('myScript:hotwireComplete')
    end
end)
```

***

## Key Names Reference

Common keys you can use in `inputBlock.keys`:

`ESC`, `F1`–`F10`, `TAB`, `ENTER`, `SPACE`, `BACKSPACE`\
`A`–`Z`, `0`–`9`\
`LEFT`, `RIGHT`, `TOP`, `DOWN`\
`LEFTSHIFT`, `LEFTCTRL`, `LEFTALT`\
`HOME`, `PAGEUP`, `PAGEDOWN`, `DELETE`

## Related pages

- [Callbacks](/koja-lib/api-reference/client-api/callbacks) — koja-lib provides a callback system that lets client scripts request data from the server and vice versa.
- [Inventory](/koja-lib/api-reference/client-api/inventory) — Client-side inventory functions let you check what items the local player has without a server round-trip.
- [DUI](/koja-lib/api-reference/client-api/dui) — DUI (Dynamic UI) allows you to render a web page as a texture on any in-game surface — screens, billboards, laptops, phones, etc.
- [Money](/koja-lib/api-reference/client-api/money) — Retrieve the local player's money balance from the client side via a server callback.
- [Keybinds](/koja-lib/api-reference/client-api/keybinds) — Register persistent key bindings that players can rebind in the GTA V settings menu.
- [Notifications](/koja-lib/api-reference/client-api/notifications) — koja-lib provides two notification interfaces: SendNotify (routes through the configured backend) and LibNotify (built-in koja-lib notification).
- [Client API](/koja-lib/api-reference/client-api) — back to the section overview