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.jsStep-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
| Action | Expected result |
|---|---|
Start the resource while logged in; run /report | Form opens, keyboard/mouse focus belongs to NUI |
| Submit a valid report | Explicit "demo only" success; no database/dispatch claim |
| Submit malformed objects or unknown categories in staging | Server rejection, no Lua type error |
| Submit twice rapidly | Busy or rate-limit response, not parallel callback replacement |
| Close/Escape during a pending request | UI closes; late reply cannot overwrite a reopened session |
| Delay the server response beyond the timeout | Browser receives an error; client does not launch another same-name request |
| Logout or restart the resource with the form open | UI hides and game focus returns |
| Rename the resource folder | Browser 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
- Safe server events: authorization before adding storage or dispatch.
- PlayerData: lifecycle and correct update payloads.
- Debugging: inspect browser, client and server separately.
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.
Weapon license
Configure the current QBCore weapon-license flow across qb-policejob, PlayerData metadata, qb-cityhall and qb-shops, including grantlicense and revokelicense.
Item Use Effect
Build a complete QBCore coffee item resource with the correct items.lua fields, server-side consumption, cooldown, client effect and cleanup.
