# qb-input

`qb-input` opens a client-side form through `exports['qb-input']:ShowInput(...)`. It returns submitted values, or `nil` when closed. Field names become the keys you read from the result. The example below is a complete local preview resource: there is no missing server event and no claim that form submission saves data.

**Source baseline:** [379f8b74](https://github.com/qbcore-fivem/qb-input/tree/379f8b7467709ea8a5dac3c800063e8118900297). Field types, options and styling conventions come from its [README](https://github.com/qbcore-fivem/qb-input/blob/379f8b7467709ea8a5dac3c800063e8118900297/README.md). The walkthrough is source-reviewed; execute the staging checks yourself before adapting it.

## Where the example belongs

Create `resources/[local]/qbnet-input-demo/`. Start `qb-input` and its dependencies on a working staging server first. The form must run in a **client** script, not a server Lua file or an ordinary web browser.

### fxmanifest.lua

```lua
fx_version 'cerulean'
game 'gta5'
client_script 'client.lua'
dependency 'qb-input'
```

### client.lua

```lua
local formOpen = false
local categories = { general = true, vehicle = true }

RegisterCommand('qbnet-form', function()
    if formOpen then return end
    if GetResourceState('qb-input') ~= 'started' then
        print('[form-demo] Start qb-input first.')
        return
    end

    formOpen = true
    local ok, result = pcall(function()
        return exports['qb-input']:ShowInput({
            header = 'Local note preview',
            submitText = 'Preview',
            inputs = {
                {
                    text = 'Note (maximum 80 bytes)',
                    name = 'note',
                    type = 'text',
                    isRequired = true
                },
                {
                    text = 'Priority (1 to 5)',
                    name = 'priority',
                    type = 'number',
                    default = 1,
                    isRequired = true
                },
                {
                    text = 'Category',
                    name = 'category',
                    type = 'select',
                    default = 'general',
                    options = {
                        { value = 'general', text = 'General' },
                        { value = 'vehicle', text = 'Vehicle' }
                    }
                }
            }
        })
    end)
    formOpen = false

    if not ok then
        print('[form-demo] Form failed; inspect the qb-input client error.')
        return
    end
    if result == nil then
        print('[form-demo] Cancelled; nothing was saved.')
        return
    end
    if type(result) ~= 'table' then return end

    local note = type(result.note) == 'string' and result.note or ''
    note = note:match('^%s*(.-)%s*$')
    local priority = tonumber(result.priority)
    local category = result.category

    if #note == 0 or #note > 80 then
        print('[form-demo] Enter a note of 1 to 80 bytes.')
        return
    end
    if not priority or priority % 1 ~= 0 or priority < 1 or priority > 5 then
        print('[form-demo] Priority must be an integer from 1 to 5.')
        return
    end
    if type(category) ~= 'string' or not categories[category] then
        print('[form-demo] Choose a listed category.')
        return
    end

    print(('[form-demo] Preview only: category=%s priority=%d noteBytes=%d'):format(
        category, priority, #note
    ))
end, false)
```

The demo intentionally logs only category, priority and note length, not the note itself. Lua's `#` measures string bytes here, so non-ASCII text can reach the limit before 80 visible characters. Adapt the validation and user-facing label together for a production multilingual form.

In the **server console**, run `refresh`, then `ensure qbnet-input-demo`. In **in-game chat**, run `/qbnet-form`. Read the preview result in F8. In F8 itself, the command is `qbnet-form` without a slash. Close the form before stopping the demo resource.

The manifest format follows [Cfx.re's resource reference](https://docs.fivem.net/docs/scripting-reference/resource-manifest/). There is no SQL import, saved note, billing action or `myresource:server:saveNote` dependency in this demo.

## Choose field names and options

| Type | Suitable use | Important detail |
| --- | --- | --- |
| `text` | Short labels or notes | Give it a unique `name`; bound length where used |
| `password` | Masked presentation of a non-sensitive game value | Masking does not secure the data flow |
| `number` | Numeric input | Convert and validate; do not assume a Lua number |
| `radio` | One choice | Match defaults to an option's `value` |
| `checkbox` | Several selections | Inspect the README's option/return conventions before consuming them |
| `select` | One choice from a list | Allowlist the submitted value, not the displayed label |
| `color` | A color choice | Validate the expected color format at its destination |

Supported fields include `text`, `name`, `type`, `isRequired`, `default` and, for relevant types, `options`. Use lowercase type names. Reusing the same field name can overwrite the result you expected. Optional fields may not supply the value your code assumes; check before indexing or converting.

## Saving data safely

The example performs no persistent action. To add one, design a separate server handler: obtain the player from the connection's source, validate the types and bounds again, check ownership or job permission against server-owned state, apply rate limits, then report the actual persistence result.

Never accept a client-supplied owner ID, price or permission flag as authority. `isRequired` and the number field are interface helpers, not server protection. A selected plate is not proof of vehicle ownership. Use [safe server events](/docs/security/safe-server-events) and the [NUI callback guide](/docs/guides/nui-form-callback) for that boundary.

Do not collect real account passwords through an in-game form. Avoid logging full player-submitted values while diagnosing an issue.

## Customize qb-input styling

The pinned README describes copying `html/styles/default.css` to a named stylesheet and setting `Config.Style` to that name. Verify the file is packaged and loaded on staging. Keep field names, option values, submit handling and cancellation intact while styling.

For a list of actions rather than form fields, use [qb-menu](/docs/resources/qb-menu). For a fully custom browser interface, follow the [NUI form guide](/docs/guides/nui-form-callback) instead of replacing qb-input's contract accidentally.

## Troubleshooting and acceptance checks

| Test or symptom | Expected result or diagnosis |
| --- | --- |
| Submit a short note with priority 1 | F8 shows a preview, not a saved-record message |
| Cancel the form | Cancellation is handled before reading result fields |
| Submit empty/whitespace-only text | Required-field or local validation rejects it |
| Supply an out-of-range or fractional priority | Integer/range check rejects it |
| Select each category | The returned value matches the allowlist |
| Open repeatedly | No second local demo form opens while the first is active |
| No form appears | Check client context, dependency startup and the first Lua/NUI error |
| Field is missing | Check cancellation, optional status and exact unique `name` |
| A custom save feature does nothing | Inspect its separate server handler and database result |

These are manual FiveM test instructions, not completed runtime results. To undo the demo, close it, stop `qbnet-input-demo` and remove its startup entry; no player data needs restoring. Return to [resource references](/docs/resources).
