# Keybinds

Register persistent key bindings that players can rebind in the GTA V settings menu.

## KOJA.registerKeyBind

```lua
local bind = KOJA.registerKeyBind(data)
```

Also available as an export:

```lua
local bind = exports['koja-lib']:registerKeyBind(data)
```

### Parameters

| Field         | Type       | Required | Description                                 |
| ------------- | ---------- | -------- | ------------------------------------------- |
| `name`        | `string`   | Yes      | Internal unique name (used as command name) |
| `description` | `string`   | Yes      | Description shown in the keybind menu       |
| `key`         | `string`   | Yes      | Default key (e.g. `"E"`, `"F5"`, `"SPACE"`) |
| `onPress`     | `function` | No       | Called when the key is pressed              |
| `onRelease`   | `function` | No       | Called when the key is released             |

**Returns** `bind` — a keybind object.

## Keybind Object

| Property / Method     | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `bind.key`            | The currently assigned key (reflects player rebinds) |
| `bind:isPressed()`    | Returns `true` while the key is held                 |
| `bind:disable(state)` | Pass `true` to disable, `false` to re-enable         |

## Examples

### Simple press action

```lua
local bind = KOJA.registerKeyBind({
    name        = 'myScript_open',
    description = 'Open shop menu',
    key         = 'F5',
    onPress     = function()
        TriggerEvent('myScript:openMenu')
    end,
})
```

### Press and release (toggle flashlight)

```lua
KOJA.registerKeyBind({
    name        = 'myScript_flashlight',
    description = 'Toggle flashlight',
    key         = 'L',

    onPress = function()
        SetFlashLightKeepOnWhileMoving(true)
        SetPedIlluminatedAlpha(PlayerPedId(), 255)
    end,

    onRelease = function()
        SetFlashLightKeepOnWhileMoving(false)
    end,
})
```

### Check if pressed in a loop

```lua
local sprint = KOJA.registerKeyBind({
    name        = 'myScript_sprint',
    description = 'Sprint modifier',
    key         = 'LEFTSHIFT',
})

CreateThread(function()
    while true do
        Wait(0)
        if sprint:isPressed() then
            -- do something every frame while held
        end
    end
end)
```

### Temporarily disable

```lua
local bind = KOJA.registerKeyBind({ ... })

-- Disable while in a menu
bind:disable(true)

-- Re-enable when menu closes
bind:disable(false)
```

## Notes

* Binds are automatically registered with `RegisterKeyMapping` so players can rebind them in **Settings → Key Bindings → FiveM**.
* The bind is hidden from the chat suggestion list automatically.
* Binds do not fire while the pause menu is open.

## Related pages

- [Callbacks](/koja-lib/api-reference/client-api/callbacks) — koja-lib provides a callback system that lets client scripts request data from the server and vice versa.
- [Inventory](/koja-lib/api-reference/client-api/inventory) — Client-side inventory functions let you check what items the local player has without a server round-trip.
- [DUI](/koja-lib/api-reference/client-api/dui) — DUI (Dynamic UI) allows you to render a web page as a texture on any in-game surface — screens, billboards, laptops, phones, etc.
- [Money](/koja-lib/api-reference/client-api/money) — Retrieve the local player's money balance from the client side via a server callback.
- [Notifications](/koja-lib/api-reference/client-api/notifications) — koja-lib provides two notification interfaces: SendNotify (routes through the configured backend) and LibNotify (built-in koja-lib notification).
- [Player](/koja-lib/api-reference/client-api/player) — Functions for reading the local player's data on the client side.
- [Client API](/koja-lib/api-reference/client-api) — back to the section overview