> For the complete documentation index, see [llms.txt](https://ccfivem.gitbook.io/ccfivem-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ccfivem.gitbook.io/ccfivem-docs/free-resources/ui-kit-cc_lib.md).

# UI Kit (cc\_lib)

**Free resource · Standalone · Version 1.0.0**

cc\_lib is the shared user interface of all CrankChaos scripts: notifications, confirmation dialogs, input dialogs, progress bars and small text hints.

{% hint style="info" %}
cc\_lib is **optional**. Every CrankChaos script also runs without it and then uses its own built-in fallback. When cc\_lib is running, all scripts share **one** notification stack and **one** theme instead of each drawing its own.
{% endhint %}

## Features

* Notifications (`success`, `error`, `warning`, `info`) with icon, title, duration and optional close button; the same `id` replaces an existing notification instead of stacking
* Blocking confirmation dialog with tone and key/value summary lines
* Input dialog with text and number fields (required, min/max)
* Progress bar and a small text hint at the screen edge
* One server-wide notification position for every CrankChaos script
* Theme presets or a custom accent colour, corner radius, UI scale, animations, blur and UI sounds
* Optional takeover of ESX notifications (`esx:showAdvancedNotification`) in CrankChaos style
* Takes NUI focus only while a confirmation or input dialog is open — notifications, progress and hints never interrupt driving
* English and German included; more languages as a file in `locales/`

## Frameworks

cc\_lib itself is framework-agnostic. Only the optional ESX notification takeover concerns ESX Legacy. The CrankChaos scripts that use it run on ESX Legacy, QBCore and QBox — see Framework Bridge.

## Pages

* Installation
* Configuration
* API
* FAQ

Related: cc\_images%20(cc\_images)/00%20Overview\.md) · cc\_jobs/00%20Overview\.md) · Support

## Installation

### Dependencies

| Resource      | Required? | Purpose                                         |
| ------------- | --------- | ----------------------------------------------- |
| —             | —         | cc\_lib has **no** required dependencies        |
| `es_extended` | optional  | ESX notifications are shown in CrankChaos style |

No SQL, no jobs, no items and no ACE permissions are needed.

### Steps

1. Copy the folder to `resources/[crankchaos]/cc_lib`.
2. Start it in `server.cfg` **before** the CrankChaos scripts that use it:

```cfg
ensure cc_lib
## then the other CrankChaos scripts, e.g.
ensure cc_garage
ensure cc_inventory
```

3. Restart the server.

{% hint style="info" %}
If cc\_lib starts after a script, that script keeps using its built-in fallback. Nothing breaks — just keep cc\_lib first.
{% endhint %}

### Framework-specific steps

None. On ESX Legacy the notification takeover is active by default; see Configuration to disable it.

See also: General installation · Dependencies

## Configuration

All settings live in `config/ui.lua`. Texts are in `locales/en.json` and `locales/de.json`. Change a value and restart the resource — no build step is needed.

### Appearance (`Config.UI`)

```lua
Config.UI = {
    theme = 'default',      -- 'default' | 'blue' | 'red' | 'green' | 'custom'
    primary = '#8B5CF6',    -- accent colour, overrides the preset
    radius = 'md',          -- 'sharp' | 'sm' | 'md' | 'lg'
    scale = 1.0,            -- 0.85 to 1.25
    locale = 'de',          -- 'de' or 'en'
    animations = true,
    blur = false,
    sounds = true,
}
```

| Option       | Meaning                                                                                                         |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| `theme`      | Colour preset                                                                                                   |
| `primary`    | Accent colour; hover, active, surface, text colour and focus ring are derived from it                           |
| `radius`     | Corner rounding                                                                                                 |
| `scale`      | Size of the whole interface                                                                                     |
| `locale`     | Language; add more languages as a JSON file in `locales/`                                                       |
| `animations` | `false` sets every duration to 1 ms — fully usable, just without motion                                         |
| `blur`       | Backdrop blur behind dialogs. Costs CEF render time every frame while a dialog is open, so it is off by default |
| `sounds`     | UI sounds (click, toggle, dialogs, notifications) for all players                                               |

{% hint style="info" %}
The shipped default is `locale = 'de'`. Set it to `'en'` for an English server.
{% endhint %}

### Notifications (`Config.Notifications`)

```lua
Config.Notifications = {
    position = 'top-left',  -- 'top-left' | 'top-right' | 'top-center' | 'bottom-right' | 'bottom-left'
    duration = 4000,        -- ms, 0 = stays until closed
}
```

| Option       | Meaning                                                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `position`   | Applies to the **whole server**: while cc\_lib runs, every CrankChaos script sends its notifications here             |
| `duration`   | Default display time in ms                                                                                            |
| `replaceEsx` | Not in the shipped file (defaults to on). Add `replaceEsx = false` to stop cc\_lib from taking over ESX notifications |

### Debug

```lua
Config.Debug = false  -- in-game debug overlay, keep off on live servers
```

## Exports, Events & Commands

All exports are **client-side**. cc\_lib has no server exports, no commands, no key mappings and no public events.

### Notify(opts)

Shows a notification. `message` is required. No return value.

```lua
exports.cc_lib:Notify({
    id       = 'garage:parked',  -- same id replaces instead of stacking
    type     = 'success',        -- success | error | warning | info
    title    = 'Garage',
    message  = 'Adder parked.',
    duration = 4000,             -- 0 = stays
    icon     = 'car',
    closable = true,
    position = 'top-right',      -- default: Config.Notifications.position
})
```

### Confirm(opts) → boolean

Blocks the calling thread. ESC, clicking outside and timeout (`timeout`, default 60000 ms) return `false`. Returns `false` immediately if a confirmation is already open.

```lua
local ok = exports.cc_lib:Confirm({
    title        = 'Sell vehicle?',
    description  = 'This cannot be undone.',
    tone         = 'danger',
    confirmLabel = 'Sell',
    meta = {
        { label = 'Vehicle', value = 'Adder' },
        { label = 'Price', value = '$352,000', emphasis = true, tone = 'success' },
    },
})
```

### Input(opts) → table | nil

Returns a table keyed by field `id`, or `nil` on cancel/timeout (`timeout`, default 120000 ms).

```lua
local values = exports.cc_lib:Input({
    title  = 'Transfer money',
    fields = {
        { id = 'account', type = 'text',   label = 'Account', required = true },
        { id = 'amount',  type = 'number', label = 'Amount', min = 1, max = 50000 },
    },
})
if values then print(values.amount) end
```

### Progress(opts) → true

Blocks for `duration` ms (default 3000). Takes no focus.

```lua
exports.cc_lib:Progress({ label = 'Repairing …', duration = 5000 })
```

### TextUI(text, opts) / HideTextUI()

Small hint at the screen edge, without focus. `opts`: `icon`, `position`.

```lua
exports.cc_lib:TextUI('[E] Open garage', { icon = 'car' })
exports.cc_lib:HideTextUI()
```

### Listened events

| Event                          | Note                                                                                           |
| ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `esx:showAdvancedNotification` | Shown as a cc\_lib notification on ESX; disable with `Config.Notifications.replaceEsx = false` |

### Focus

NUI focus is taken **only** while `Confirm` or `Input` is open, and is released when the resource stops.

## FAQ & Troubleshooting

**Do I need cc\_lib?** No. Every CrankChaos script runs without it using its own fallback. With cc\_lib you get one shared notification stack and one theme.

**Notifications from my scripts still look different.** Make sure `ensure cc_lib` comes **before** the other CrankChaos scripts in `server.cfg`, then restart them.

**A second `Confirm` / `Input` returns `false` / `nil` immediately.** Only one confirmation and one input dialog can be open at a time. This is intended.

**The progress bar does not cancel when I move.** `Progress` is purely visual: it does not cancel on movement or damage and plays no animation. The calling script handles that.

**Some GTA feed messages disappear on ESX.** When taking over ESX notifications the GTA feed queue is flushed; other feed messages arriving at the same moment are lost. Add `replaceEsx = false` to `Config.Notifications` if this matters to you.

**The UI is in German.** Set `Config.UI.locale = 'en'` in `config/ui.lua` and restart the resource.

**Dialogs feel slow on weaker PCs.** Keep `Config.UI.blur = false`; optionally set `animations = false`.

Still stuck? See Support.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ccfivem.gitbook.io/ccfivem-docs/free-resources/ui-kit-cc_lib.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.