Progress

Timed progress bars and circles with animations, prop attachments, and input control.

Client Exports

progressBar

Show a linear progress bar.


local completed = exports['trinity-ui']:progressBar(data)

progressCircle

Show a circular progress indicator.


local completed = exports['trinity-ui']:progressCircle(data)

showProgress

Generic progress display — use the type property to choose bar or circle.


local completed = exports['trinity-ui']:showProgress(data)

All three are awaitable and return true on completion or false if cancelled.

Properties:

Property	Type	Default	Description
`title`	`string`	—	Progress label (alias: `label`)
`description`	`string`	—	Secondary text
`icon`	`string`	—	Iconify icon name
`duration`	`number`	—	Duration in milliseconds
`percentage`	`number`	—	Static percentage (0-100)
`type`	`string`	`'bar'`	`'bar'` \| `'circle'` (for `showProgress`)
`minimal`	`boolean`	—	Compact display
`segments`	`number`	—	Number of progress segments
`canCancel`	`boolean`	`false`	Allow cancellation with X key
`useWhileDead`	`boolean`	`false`	Allow while player is dead
`allowRagdoll`	`boolean`	`false`	Allow while ragdolling
`allowCuffed`	`boolean`	`false`	Allow while cuffed
`allowFalling`	`boolean`	`false`	Allow while falling
`allowSwimming`	`boolean`	`false`	Allow while swimming
`disable`	`table`	—	Input disabling options (see below)
`anim`	`table`	—	Animation to play during progress
`prop`	`table \| table[]`	—	Prop(s) to attach to player

Disable Options:


disable = {
    mouse = true,    -- Disable mouse look
    move = true,     -- Disable movement
    sprint = true,   -- Disable sprinting
    car = true,      -- Disable vehicle controls
    combat = true    -- Disable combat
}

Animation:


anim = {
    dict = 'amb@prop_human_bbq@male@base',  -- Animation dictionary
    clip = 'base',                           -- Animation clip name
    flag = 49                                -- Animation flag (default 49)
}
-- OR use a scenario:
anim = {
    scenario = 'PROP_HUMAN_BBQ'
}

Props:


prop = {
    model = 'prop_tool_hammer',     -- Prop model name or hash
    bone = 60309,                   -- Bone index (default: right hand)
    pos = vector3(0.0, 0.0, 0.0),  -- Position offset
    rot = vector3(0.0, 0.0, 0.0)   -- Rotation offset
}
-- Multiple props:
prop = {
    { model = 'prop_tool_hammer', bone = 60309, pos = vec3(0.0, 0.0, 0.0), rot = vec3(0.0, 0.0, 0.0) },
    { model = 'prop_tool_wrench', bone = 28422, pos = vec3(0.0, 0.0, 0.0), rot = vec3(0.0, 0.0, 0.0) }
}

updateProgress

Update the percentage of an active progress display.


exports['trinity-ui']:updateProgress(percentage)

cancelProgress

Cancel the active progress display.


exports['trinity-ui']:cancelProgress()

isProgressActive

Check if a progress display is currently active.


local active = exports['trinity-ui']:isProgressActive()

Example


-- Simple progress bar
local success = exports['trinity-ui']:progressBar({
    title = 'Repairing Vehicle',
    duration = 8000,
    canCancel = true,
    disable = {
        move = true,
        combat = true
    },
    anim = {
        dict = 'mini@repair',
        clip = 'fixing_a_player'
    },
    prop = {
        model = 'prop_tool_wrench',
        bone = 60309,
        pos = vec3(0.0, 0.0, -0.03),
        rot = vec3(-90.0, 0.0, 0.0)
    }
})
 
if success then
    print('Vehicle repaired!')
else
    print('Repair cancelled.')
end


-- Circle progress
exports['trinity-ui']:progressCircle({
    title = 'Searching...',
    duration = 5000,
    icon = 'fa6-solid:magnifying-glass'
})

The cancel keybind is X by default and can be rebound by the player through FiveM’s keybind settings.