# Progress Bar (/docs/orbit-studios-resources/orbit-dynamichud/interface/progress-bar)



# Progress Bar [#progress-bar]

`progressBar` yields the calling Lua thread and returns `true` when the duration completes. It returns `false` when cancelled, interrupted by a disallowed ped state, timed out, or rejected because another progress action is active.

```lua title="Client export"
local completed = exports['orbit-dynamichud-v2']:progressBar({
    label = 'Repairing vehicle',
    description = 'Keep the area clear.',
    duration = 5000,
    canCancel = true,
    keybind = 'X',
    disable = {
        move = true,
        car = true,
        combat = true,
        sprint = true
    },
    anim = {
        dict = 'mini@repair',
        clip = 'fixing_a_ped',
        flag = 49
    }
})

if completed then
    TriggerServerEvent('my-resource:finishRepair')
end
```

## Options [#options]

| Field                    | Type       | Default     | Description                                                                      |                                         |
| ------------------------ | ---------- | ----------- | -------------------------------------------------------------------------------- | --------------------------------------- |
| `id`                     | `string?`  | generated   | Run ID used to match completion and cancellation.                                |                                         |
| `label`                  | `string?`  | empty       | Main text.                                                                       |                                         |
| `description`            | `string?`  | empty       | Supporting text.                                                                 |                                         |
| `labelTranslation`       | `string?`  | none        | Frontend locale key used instead of `label` when found.                          |                                         |
| `descriptionTranslation` | `string?`  | none        | Frontend locale key used instead of `description` when found.                    |                                         |
| `duration`               | `number?`  | `3000`      | Milliseconds. Supply it explicitly; Lua adds a two-second watchdog grace period. |                                         |
| `canCancel`              | `boolean?` | `true`      | Whether the player can cancel. `cancellable` is an alias.                        |                                         |
| `keybind`                | `string?`  | `"X"`       | Key shown in the interface. `cancelKey` is an alias.                             |                                         |
| `cancelControl`          | `number?`  | derived     | GTA control ID. Use it when a custom key label has no built-in mapping.          |                                         |
| `disable`                | `table?`   | none        | Control groups disabled while active.                                            |                                         |
| `anim`                   | `table?`   | none        | Animation dictionary/clip or scenario.                                           |                                         |
| `prop`                   | \`table    | table\[]?\` | none                                                                             | One attached prop or an array of props. |
| `useWhileDead`           | `boolean?` | `false`     | Allow progress while dead or fatally injured.                                    |                                         |
| `allowRagdoll`           | `boolean?` | `false`     | Allow progress while ragdolling.                                                 |                                         |
| `allowSwimming`          | `boolean?` | `false`     | Allow progress while swimming or underwater.                                     |                                         |
| `allowCuffed`            | `boolean?` | `false`     | Allow progress while cuffed.                                                     |                                         |
| `allowFalling`           | `boolean?` | `false`     | Allow progress while falling.                                                    |                                         |

Supported `disable` keys are `move`, `car`, `combat`, `mouse`, and `sprint`.

## Animations and scenarios [#animations-and-scenarios]

```lua title="Animation"
anim = {
    dict = 'amb@world_human_hammering@male@base',
    clip = 'base',
    blendIn = 3.0,
    blendOut = 1.0,
    duration = -1,
    flag = 49,
    playbackRate = 0.0,
    lockX = false,
    lockY = false,
    lockZ = false
}
```

```lua title="Scenario"
anim = {
    scenario = 'WORLD_HUMAN_WELDING',
    playEnter = true
}
```

`anim` is accepted as an alias for `clip`; `flags` is accepted as an alias for `flag`.

## Props [#props]

```lua
prop = {
    model = 'prop_tool_box_04',
    bone = 60309,
    pos = vec3(0.0, 0.0, 0.0),
    rot = vec3(0.0, 0.0, 0.0),
    rotOrder = 0
}
```

`model` may be a model name or hash. `pos` and `rot` accept `vector3`, named `{ x, y, z }` tables, or numeric arrays. Loaded animations and spawned props are cleaned up when the action ends or the resource stops.

## State and cancellation [#state-and-cancellation]

```lua
if exports['orbit-dynamichud-v2']:progressActive() then
    exports['orbit-dynamichud-v2']:cancelProgress()
end
```

## ox\_lib drop-in replacement [#ox_lib-drop-in-replacement]

```lua title="client/orbit_progress.lua"
lib = lib or {}

lib.progressBar = function(data)
    return exports['orbit-dynamichud-v2']:progressBar(data)
end

-- Keeps existing progressCircle calls functional using DynamicHUD's progress view.
lib.progressCircle = lib.progressBar

lib.progressActive = function()
    return exports['orbit-dynamichud-v2']:progressActive()
end

lib.cancelProgress = function()
    return exports['orbit-dynamichud-v2']:cancelProgress()
end
```

The data structure and boolean return behavior are compatible with ox\_lib. DynamicHUD provides one progress presentation, so both ox\_lib entry points render the DynamicHUD progress bar and `progressCircle.position` has no visual effect.

The local event `orbit-dynamichud:progressBarOver` receives the NUI result table. Use the export return value for ordinary gameplay logic.