QBCore Frameworkqbcore.netCommunity docs
On this page

Updated 2026-09-26 · 4 min read

Goal

Build an incident-report validation demo with a working browser/game/server round trip. It intentionally does not store reports or send dispatch alerts; successful validation says so. All six required files are included, with no missing config.lua or stylesheet.

Overview

Download the complete NUI example. The ZIP is generated from the repository's examples/docs-nui-form source during pnpm build; it is not a separately maintained copy. Extract the docs-nui-form folder into resources/[local].

Test boundary: source-reviewed and mock-tested. Actual FiveM focus, keyboard interaction and resource-restart acceptance must still be run on your staging server. No in-game certification is implied.

Resource Layout

docs-nui-form/
├── fxmanifest.lua
├── client.lua
├── server.lua
└── html/
    ├── index.html
    ├── styles.css
    └── script.js

Step-by-Step Implementation

1. Define the resource manifest

The included manifest explicitly declares every browser file and the core dependency:

fx_version 'cerulean'
game 'gta5'
dependency 'qb-core'
ui_page 'html/index.html'
files { 'html/index.html', 'html/styles.css', 'html/script.js' }
client_script 'client.lua'
server_script 'server.lua'

Add ensure docs-nui-form after core in server.cfg. Use an isolated development server with an already working QBCore character login. This example adds no SQL and requires no phone/dispatch resource.

2. Build the NUI form

html/index.html provides labelled citizen-ID, category and description fields, a submit button, a close button and a status region. The panel starts hidden. styles.css explicitly preserves [hidden], so a layout rule cannot accidentally show the form at resource startup.

The example accepts a subject ID as text; it neither verifies that the subject exists nor exposes that character's private data. Do not describe its successful reply as a saved police report.

3. Send form data to the server

html/script.js posts JSON to https://${GetParentResourceName()}/submit-incident inside FiveM NUI. It checks HTTP failure, bounds waiting with a browser timeout and prevents duplicate submits while one browser request is pending. The game resource name is obtained from the NUI environment, not a hardcoded host.

Closing or reopening advances a UI generation counter. A late result from a previous form session cannot overwrite the current status. Opening the HTML in an ordinary browser does not provide the FiveM bridge; do not replace it with an invented browser implementation of a game native.

4. Handle UI state on the client

client.lua initializes QBCore with GetCoreObject, registers /report, and handles both NUI routes: close and submit-incident. Open/close messages have matching browser listeners. Close, character unload and resource stop release focus and hide the UI.

There are two callbacks, not one: the browser's NUI callback and the client/server QBCore callback. The client completes the NUI callback on rejection, close, server response or timeout. It sends only one request at a time through the named QBCore callback. At this core revision, pending callbacks are keyed by name. After a timeout the client waits for the late server reply rather than overwriting that registry with another request of the same name. A token check rejects mismatched responses.

5. Validate and process server-side

server.lua looks up the actual caller, checks the outer payload type, rate-limits submissions and validates each string before indexing or calling string methods. Category must be on the server's allowlist. Citizen IDs are restricted to 4–32 letters/digits/underscores/hyphens; details must contain non-whitespace text and fit the 500-byte limit. The HTML character limit does not replace the server byte limit for multibyte text.

Every rejection and the successful demonstration reply invokes cb. The example does not print report contents into server logs. Cooldown state is cleared on character unload/disconnection.

Testing Checklist

ActionExpected result
Start the resource while logged in; run /reportForm opens, keyboard/mouse focus belongs to NUI
Submit a valid reportExplicit "demo only" success; no database/dispatch claim
Submit malformed objects or unknown categories in stagingServer rejection, no Lua type error
Submit twice rapidlyBusy or rate-limit response, not parallel callback replacement
Close/Escape during a pending requestUI closes; late reply cannot overwrite a reopened session
Delay the server response beyond the timeoutBrowser receives an error; client does not launch another same-name request
Logout or restart the resource with the form openUI hides and game focus returns
Rename the resource folderBrowser route still uses the runtime resource name

Repository maintainers can rebuild archives with node scripts/build-tutorial-examples.mjs and run the documented Lua harness in scripts/examples/test-complete-tutorials.lua.

Troubleshooting

UI stays hidden: inspect F8 and the NUI console; confirm the command ran after login, the manifest lists all HTML assets, and the browser receives an open message.

Callback never returns: check both route names and the QBCore callback name. A browser timeout does not prove the server operation failed. This demo blocks another same-name request until the first server response returns; restart only this example in staging after investigating the cause.

Focus stuck: test Close/Escape, character unload and resource stop. The cleanup path must run SetNuiFocus(false, false) as well as hiding the browser panel.

Next Steps

Sources

Found an issue in this guide?

Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website