> For the complete documentation index, see [llms.txt](https://laot7490.gitbook.io/ltbridge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://laot7490.gitbook.io/ltbridge/ui-and-interaction/nui.md).

# NUI

## NUI

Communicate between your Lua scripts and NUI (HTML/JS) pages. Use Message/Send for data, Focus for cursor control, and Callback for request/response.

### Functions

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Callback</strong></td><td>Registers a NUI callback/listener.</td><td><a href="#callback">#callback</a></td></tr><tr><td><strong>Check</strong></td><td>Yields the current thread until NUI signals its ready.</td><td><a href="#check">#check</a></td></tr><tr><td><strong>CreateState</strong></td><td>Creates a reactive state table for NUI.</td><td><a href="#createstate">#createstate</a></td></tr><tr><td><strong>Focus</strong></td><td>Set NUI focus and optional mouse cursor. Also triggers an event that can be listened to.</td><td><a href="#focus">#focus</a></td></tr><tr><td><strong>IsLoaded</strong></td><td>Returns `true` if NUI is loaded, `false` otherwise.</td><td><a href="#isloaded">#isloaded</a></td></tr><tr><td><strong>Message</strong></td><td>Sends a message to the NUI.</td><td><a href="#message">#message</a></td></tr><tr><td><strong>Request</strong></td><td>Sends a message to the NUI and waits for a response.</td><td><a href="#request">#request</a></td></tr><tr><td><strong>Send</strong></td><td>@deprecated.</td><td><a href="#send">#send</a></td></tr></tbody></table>

***

## Callback

Registers a NUI callback/listener.

{% hint style="info" %}
**Side:** Client · **Category:** NUI · **API:** `LT.NUI.Callback`
{% endhint %}

### Example

```lua
LT.NUI.Callback('closeMenu', function(data, cb)
    LT.NUI.Focus(false)
    cb('ok')
end)
```

### Parameters

| Name   | Required | Description                              |
| ------ | -------- | ---------------------------------------- |
| `name` | Yes      | Callback name                            |
| `cb`   | Yes      | fun(data: table, cb: fun(response: any)) |

***

## Check

Yields the current thread until NUI signals its ready.

{% hint style="info" %}
**Side:** Client · **Category:** NUI · **API:** `LT.NUI.Check`
{% endhint %}

### Example

```lua
LT.NUI.Check()
```

### Parameters

| Name     | Required | Description                                               |
| -------- | -------- | --------------------------------------------------------- |
| `action` | No       | NUI message to send (defaults to 'ltbridge\_check\_nui'). |

### Returns

* `boolean`

***

## CreateState

Creates a reactive state table for NUI.

{% hint style="info" %}
**Side:** Client · **Category:** NUI · **API:** `LT.NUI.CreateState`
{% endhint %}

### Example

```lua
local player = LT.NUI.CreateState("UpdatePlayer", {
    hud = {
        health = 100,
        armor = 100
    },
    inventory = {
        items = {
            { id = 1, name = "Apple", quantity = 1, secret = "123" }
        }
    },
    localOnly = {
        secret = "123"
    }
}, { "localOnly", "inventory.items.1.secret" })
player.hud.health = 50
player.hud.armor = 25
player.inventory.items[1].name = nil
player:update({ hud = { health = 75 } })
player:set({ hud = { health = 100, armor = 100 } })
player:sync()
```

### Parameters

| Name         | Required | Description                                                                                                               |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `action`     | Yes      | Base update action. Example: `UpdatePlayer`.                                                                              |
| `tbl`        | No       | Initial state table.                                                                                                      |
| `ignoreList` | No       | string\[] Dot-path list that will never be sent to NUI (ignored). Example: `{ "hud.health", "inventory.items.1.secret" }` |

### Returns

* `table proxy Reactive state proxy (`:sync`,` :set`,` :update`,` :raw`,` :snapshot`).`

***

## Focus

Set NUI focus and optional mouse cursor. Also triggers an event that can be listened to.

{% hint style="info" %}
**Side:** Client · **Category:** NUI · **API:** `LT.NUI.Focus`
{% endhint %}

### Example

```lua
LT.NUI.Focus(true, true) -- Focus + Mouse
LT.NUI.Focus(false)      -- Close All
AddEventHandler('ltbridge:client:@NUI:FocusChanged', function(status, cursor)
    print('NUI Focus Changed:', status, cursor)
end)
```

{% hint style="info" %}
`FocusChanged` fires on the **LTBridge** resource (`ltbridge`), not your script's resource name.
{% endhint %}

### Parameters

| Name     | Required | Description                                       |
| -------- | -------- | ------------------------------------------------- |
| `status` | Yes      | Focus status                                      |
| `cursor` | No       | Optional mouse cursor status (defaults to status) |

***

## IsLoaded

Returns `true` if NUI is loaded, `false` otherwise.

{% hint style="info" %}
**Side:** Client · **Category:** NUI · **API:** `LT.NUI.IsLoaded`
{% endhint %}

### Example

```lua
local result = LT.NUI.IsLoaded()
```

### Returns

* `boolean`

***

## Message

Sends a message to the NUI.

{% hint style="info" %}
**Side:** Client · **Category:** NUI · **API:** `LT.NUI.Message`
{% endhint %}

### Example

```lua
LT.NUI.Message('open_shop', { items = {1, 2, 3} })
```

### Parameters

| Name     | Required | Description           |
| -------- | -------- | --------------------- |
| `action` | Yes      | Action name           |
| `data`   | No       | Optional data payload |

### Send vs Message

| API                            | Payload shape                                      | Status     |
| ------------------------------ | -------------------------------------------------- | ---------- |
| `LT.NUI.Message(action, data)` | `{ action, ...data }` — fields merged at top level | Preferred  |
| `LT.NUI.Send(action, payload)` | `{ action, payload }` — nested under `payload`     | Deprecated |

***

## Request

Sends a message to the NUI and waits for a response.

{% hint style="info" %}
**Side:** Client · **Category:** NUI · **API:** `LT.NUI.Request`
{% endhint %}

### Example

```lua
local name = LT.NUI.Request('get_name', { title = 'Enter' }, 5000)
print(name)
```

### Parameters

| Name      | Required | Description                            |
| --------- | -------- | -------------------------------------- |
| `action`  | Yes      | Action name                            |
| `data`    | No       | Optional data to send                  |
| `timeout` | No       | Optional timeout in ms (default: 5000) |

### Returns

* `any?` — data returned from NUI, or `nil` on timeout

### NUI response (JavaScript)

```js
window.addEventListener('message', (event) => {
    if (event.data.action === 'get_name') {
        fetch(`https://${GetParentResourceName()}/ltbridge:response`, {
            method: 'POST',
            body: JSON.stringify({ requestId: event.data.requestId, data: 'John' }),
        })
    }
})
```

***

## Send

**Deprecated** — use `LT.NUI.Message` instead. Payload shape differs (see Send vs Message above).

{% hint style="info" %}
**Side:** Client · **Category:** NUI · **API:** `LT.NUI.Send`
{% endhint %}

### Example

```lua
LT.NUI.Send('open_shop', { items = {1, 2, 3} })
```

### Parameters

| Name      | Required | Description           |
| --------- | -------- | --------------------- |
| `action`  | Yes      | Action name           |
| `payload` | No       | Optional data payload |