> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shdevelopment.org/llms.txt
> Use this file to discover all available pages before exploring further.

# sh-progressbar: Circular Progress Bar for FiveM

> sh-progressbar renders a circular countdown ring on screen. Trigger it from any script with a single export call — no dependencies required.

sh-progressbar displays an animated circular countdown ring at the bottom-center of the screen, giving players a clear visual indicator during timed actions such as crafting, lockpicking, or harvesting. The ring fills using a CSS conic-gradient as time elapses, a live countdown timer in seconds ticks down inside the ring, and a colored label below the ring describes the current action. When the timer reaches zero the element hides itself automatically — no cleanup code required in your script. The resource is fully standalone and exposes a single Lua export, so you can call it from any client-side script without adding a framework dependency.

## Installation

<Steps>
  <Step title="Add the resource to your server">
    Place the `sh-progressbar` folder inside your server's `resources` directory.

    ```
    resources/
    └── sh-progressbar/
        ├── fxmanifest.lua
        ├── client/
        └── html/
    ```
  </Step>

  <Step title="Start the resource in server.cfg">
    Open your `server.cfg` and add the ensure line. Place it before any scripts that call the export.

    ```cfg server.cfg theme={null}
    ensure sh-progressbar
    ```
  </Step>
</Steps>

## Export Reference

Trigger the progress bar from any client-side Lua script using the `progressbar` export:

```lua theme={null}
exports['sh-progressbar']:progressbar(label, durationMs, color)
```

### Parameters

<ParamField path="label" type="string" required>
  The action text displayed below the progress ring. Keep this short and descriptive so players immediately understand what is happening.

  Example: `'Picking Lock'`
</ParamField>

<ParamField path="durationMs" type="number" required>
  The total duration of the progress bar animation, in **milliseconds**. The ring fills completely over this period and then disappears.

  Example: `5000` (5 seconds)
</ParamField>

<ParamField path="color" type="string" required>
  The color applied to the progress ring and the label text. Accepts any of the following formats:

  | Format      | Example               |
  | ----------- | --------------------- |
  | Named color | `'green'`             |
  | HEX         | `'#285a5c'`           |
  | RGB         | `'rgb(87, 196, 199)'` |
</ParamField>

## Usage Examples

<Tabs>
  <Tab title="HEX Color">
    ```lua theme={null}
    exports['sh-progressbar']:progressbar('Processing...', 5000, '#827f20')
    ```
  </Tab>

  <Tab title="Named Color">
    ```lua theme={null}
    exports['sh-progressbar']:progressbar('Harvesting Weed', 10000, 'green')
    ```
  </Tab>

  <Tab title="RGB Color">
    ```lua theme={null}
    exports['sh-progressbar']:progressbar('Picking Lock', 8000, 'rgb(200, 100, 50)')
    ```
  </Tab>
</Tabs>

## Pairing With Actions

The progress bar is visual only — it does not block player input or pause script execution by itself. To prevent players from moving or acting during a timed action, add your own control-disabling logic around the export call and use a coroutine or `Wait()` to match the duration.

```lua theme={null}
-- Example: disable controls, show progress bar, then execute action
DisableAllControlActions(0)
exports['sh-progressbar']:progressbar('Picking Lock', 8000, 'rgb(200, 100, 50)')
Wait(8000)
EnableAllControlActions(0)
-- run your post-action code here
```

<Warning>
  Calling the export while a progress bar is already on screen will restart the animation immediately. Add a guard flag in your script to prevent players from triggering overlapping progress bars.
</Warning>

<Tip>
  Match your `durationMs` value and any `Wait()` call exactly so the bar disappears at the same moment your action resolves — a mismatch creates a confusing experience where the ring ends before or after the action completes.
</Tip>