> For the complete documentation index, see [llms.txt](https://code-after-sex.gitbook.io/script-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-after-sex.gitbook.io/script-documentation/cas-progressbar/cas-progressbar.md).

# CAS Progressbar

`cas-progressbar` is a modern, NUI-based progress bar for **RedM**. Built with a React + TypeScript frontend and a lightweight Lua client, it drops into any script, is highly configurable, and can play animations and attach props while an action runs.

## Highlights

* Clean, animated NUI bar with duration-based fill
* Custom label, color, icon (react-icons Fa6) and screen position
* Cancel key (default H) and optional control disabling (movement, vehicle, mouse, combat)
* Optional animation (scenario or animDict/anim) and prop attachment
* Locale support (EN/FR) and a `/testprogressbar` debug command
* Exports + event API, plus a "busy" state helper
* Framework-agnostic — works with any framework or none

## At a glance

|               |                                                 |
| ------------- | ----------------------------------------------- |
| Platform      | RedM                                            |
| Framework     | Any (or none)                                   |
| Resource name | `cas-progressbar`                               |
| Config        | `config/client_config.lua`, `config/locale.lua` |

## Installation

1. Place `cas-progressbar` in your `resources` folder.
2. Add `ensure cas-progressbar` to your `server.cfg`.

There is no server-side Lua — everything runs client-side and NUI.

## Configuration

### `config/client_config.lua`

```lua
Config = {
    escapeKey = { label = "Escape", id = 0x24978A28 },  -- cancel key (default H)
    debug = true,                                        -- enables /testprogressbar
    -- Notify = function(message) exports['your-notify']:Show(message) end,
}
```

### `config/locale.lua`

```lua
Locale = 'en'
Locales = {
    ["en"] = { ["escape"] = "H to Cancel", ["cancelled"] = "Action Cancelled" },
    ["fr"] = { ["escape"] = "H pour annuler", ["cancelled"] = "Action annulee" },
}
```

Add a language by extending `Locales` and setting `Locale`. Icons come from the `react-icons` Font Awesome 6 set — use exact names (e.g. `FaSmoking`, `FaHammer`).

## API

### Export — `Progress(action, finishCallback)`

```lua
local action = {
    name = "repair_vehicle",
    duration = 8000,
    label = "Repairing the vehicle...",
    canCancel = true,
    useWhileDead = false,
    useWhileMounted = false,
    cancelKey = Config.escapeKey.id,
    controlDisables = { disableMovement = true, disableVehicleMovement = true, disableMouse = true, disableCombat = true },
    animation = { scenario = "WORLD_HUMAN_SMOKE_CARRYING" },
    prop = { model = "p_cigarette01x", bone = 28422, pos = { x=0.0, y=0.0, z=0.0 }, rot = { x=0.0, y=0.0, z=0.0 } },
    icon = "FaHammer",
    color = "#EAC48B",
    position = "bottom-center",
}

exports["cas-progressbar"]:Progress(action, function(cancelled)
    if cancelled then print("Cancelled") else print("Finished") end
end)
```

`finishCallback(cancelled)` receives `true` if cancelled, `false` if completed.

### Export — `isDoingSomething()`

```lua
if exports["cas-progressbar"]:isDoingSomething() then return end
```

### Events

```lua
TriggerEvent("cas-progressbar:client:progress", action, function(cancelled) end)
TriggerEvent("cas-progressbar:client:cancel")
TriggerEvent("cas-progressbar:client:ToggleBusyness", true)
```

## Action object reference

| Field                                        | Description                                          |
| -------------------------------------------- | ---------------------------------------------------- |
| `name`                                       | Internal action name                                 |
| `duration`                                   | Length in ms                                         |
| `label`                                      | Title text on the bar                                |
| `canCancel`                                  | Allow cancel key (default true)                      |
| `useWhileDead`                               | If false, cancels when dead (default false)          |
| `useWhileMounted`                            | If false, cancels when mounted (default true)        |
| `cancelKey`                                  | Control hash to cancel                               |
| `controlDisables`                            | Toggle movement / vehicle / mouse / combat           |
| `animation`                                  | `scenario`, or `animDict` + `anim` (+ `flag`)        |
| `prop`                                       | `model`, `bone`, `pos`, `rot` attached to the player |
| `icon`                                       | react-icons Fa6 name                                 |
| `color`                                      | Hex color (default `#A78E77`)                        |
| `position`                                   | top / center / bottom + left/right combos            |
| `onStart` / `onTick` / `onFinish(cancelled)` | Lifecycle callbacks                                  |

## Debug

With `Config.debug = true`, run `/testprogressbar` to preview a sample 5-second action (smoking scenario + cigarette prop).

## Troubleshooting

* **Bar not appearing** — ensure the resource started, `web/build` exists, and no other NUI blocks focus; try `/testprogressbar`.
* **Cancel key not working** — `Config.escapeKey.id` must match your control; keep `escapeKey.label` and `Locales[Locale].escape` consistent.
* **Overlapping actions** — the script blocks new actions while one is active; check with `isDoingSomething()`.

## Support

Join the [CAS Discord](https://discord.gg/X8bTK9Stwk) or use the support channel on your product page.