> For the complete documentation index, see [llms.txt](https://docs.kojascripts.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kojascripts.eu/koja-lib/api-reference/client-api/keybinds.md).

# 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.


---

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kojascripts.eu/koja-lib/api-reference/client-api/keybinds.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.