> For the complete documentation index, see [llms.txt](https://docs.kojascripts.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kojascripts.eu/koja-lib/api-reference/client-api/progress-bar.md).

# 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`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kojascripts.eu/koja-lib/api-reference/client-api/progress-bar.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.