> For the complete documentation index, see [llms.txt](https://dirkscripts.gitbook.io/dirkscripts-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dirkscripts.gitbook.io/dirkscripts-documentation/resources/dirk-cfx-react/hooks-and-utilities.md).

# Hooks & Utilities

## Hooks

### useNuiEvent

Listens for NUI messages from Lua client scripts. Manages event listener lifecycle automatically.

```tsx
import { useNuiEvent } from "dirk-cfx-react";

useNuiEvent<{ visibility: boolean }>("SET_VISIBLE", (data) => {
  setVisible(data.visibility);
});
```

| Parameter | Type                | Description                               |
| --------- | ------------------- | ----------------------------------------- |
| `action`  | `string`            | The NUI event name to listen for          |
| `handler` | `(data: T) => void` | Callback fired when the event is received |

The handler ref is updated on every render so you always have access to the latest closure values without re-registering the event listener.

{% hint style="info" %}
The Lua side sends NUI messages with `SendNUIMessage({ action = 'SET_VISIBLE', data = { visibility = true } })`.
{% endhint %}

### useAudio

Zustand store for playing audio files via NUI.

```tsx
import { useAudio } from "dirk-cfx-react";

const { play, stop } = useAudio();
play("click.ogg");
```

### useTornEdges

Generates torn/ripped edge clip paths for paper-style UI elements.

***

## Utilities

### fetchNui

Sends a POST request to the Lua client via FiveM's NUI callback system.

```tsx
import { fetchNui } from "dirk-cfx-react";

const result = await fetchNui<{ success: boolean }>("MY_EVENT", { id: 123 });
```

| Parameter   | Type      | Description                                      |
| ----------- | --------- | ------------------------------------------------ |
| `eventName` | `string`  | NUI callback name registered in Lua              |
| `data`      | `unknown` | Payload to send                                  |
| `mockData`  | `T`       | Return this when running in a browser (dev mode) |

When running in a browser environment (outside FiveM), `fetchNui` returns `mockData` if provided, or an empty object with a console warning.

### locale

Locale string resolver. Fetches translations from the server via `GET_LOCALES` and supports `%s` placeholder substitution.

```tsx
import { locale } from "dirk-cfx-react";

locale("FishCaught");              // → "Fish Caught"
locale("XPGained", "150", "Bass"); // → "You gained 150 XP from Bass"
```

| Parameter | Type       | Description                                |
| --------- | ---------- | ------------------------------------------ |
| `key`     | `string`   | Locale key                                 |
| `...args` | `string[]` | Values to substitute for `%s` placeholders |

Locale strings are loaded from your resource's `locales/en.json` (or whichever language is configured).

### useSettings

Zustand store holding server-provided settings. Populated automatically by `DirkProvider`.

```tsx
import { useSettings } from "dirk-cfx-react";

const { currency, primaryColor, itemImgPath, game } = useSettings();
```

| Key               | Type                 | Description                  |
| ----------------- | -------------------- | ---------------------------- |
| `game`            | `"fivem" \| "rdr3"`  | Current game                 |
| `currency`        | `string`             | Currency symbol (e.g. `"$"`) |
| `primaryColor`    | `string`             | Mantine colour name          |
| `primaryShade`    | `number`             | Shade index (0–9)            |
| `itemImgPath`     | `string`             | Base URL for item images     |
| `resourceVersion` | `string`             | Current resource version     |
| `customTheme`     | `MantineColorsTuple` | Custom colour palette        |

### useItems

Zustand store for inventory item definitions. Populated by the `GET_ITEMS` NUI callback.

```tsx
import { useItems, getItemImageUrl } from "dirk-cfx-react";

const items = useItems();              // Record<string, ItemDef>
const url = getItemImageUrl("bass");   // full image URL
```

### colorWithAlpha

Helper to add alpha transparency to CSS colour strings.

```tsx
import { colorWithAlpha } from "dirk-cfx-react";

colorWithAlpha("#4ade80", 0.5); // → "rgba(74, 222, 128, 0.5)"
```

### createSkill

Factory for creating RuneScape-style XP/level curves.

```tsx
import { createSkill } from "dirk-cfx-react";

const FishingSkill = createSkill({
  baseLevel: 1,
  maxLevel: 99,
  baseXP: 83,
  modifier: 1,
});

FishingSkill.getLevelForXP(5000); // → 23
FishingSkill.getXPForLevel(50);  // → 101333
```

### inputMapper

Constants for FiveM input mapper categories and key names. Used internally by `FiveMKeyBindInput`.

```tsx
import { INPUT_MAPPER_PRIMARY_OPTIONS, INPUT_MAPPER_KEYS_BY_PRIMARY } from "dirk-cfx-react";

// INPUT_MAPPER_PRIMARY_OPTIONS: ["KEYBOARD", "MOUSE_BUTTON", "PAD_DIGITALBUTTON", ...]
// INPUT_MAPPER_KEYS_BY_PRIMARY: { KEYBOARD: ["A", "B", "C", ...], ... }
```