FiveM NUI: how it works, common mistakes and the AI skill

FiveM NUI is the system that lets a resource draw its interface with HTML, CSS and JavaScript inside an embedded browser. Every custom inventory, phone, HUD and shop menu on a FiveM server is a NUI page. If you are building an interface that ox_lib does not cover, you need to understand how the page is declared, how Lua and JavaScript talk to each other, and where the security boundary sits.

What FiveM NUI gives you

The resource declares its page in fxmanifest.lua with ui_page 'html/index.html' and lists every asset the browser will load in the files {} block. The page renders fullscreen on top of the game.

• Lua to JavaScript. SendNUIMessage({ action = 'open', data = ... }) on the client sends a JSON object. The page receives it with window.addEventListener('message', ...) and reads event.data.
• Focus and cursor. SetNuiFocus(hasFocus, hasCursor) decides whether the page captures keyboard and mouse. Open with SetNuiFocus(true, true), close with SetNuiFocus(false, false).
• JavaScript to Lua. RegisterNUICallback('close', function(data, cb) ... cb('ok') end) on the client. The page calls it with fetch('https://<resource-name>/close', { method: 'POST', body: JSON.stringify(data) }). Use GetParentResourceName() in JS to get the resource name without hardcoding it.
• Security. NUI code runs on the player's machine. Anything it sends must be validated on the server before it touches money, items or the database.

The natives are documented at docs.fivem.net/natives.

Common mistakes with FiveM NUI

• Forgetting SetNuiFocus(false, false) on close. The page disappears but the player cannot move or open the pause menu. Every close path, including Escape and the close button, must release focus.
• Wrong URL in fetch. The resource folder is called my-shop but the JS calls https://myshop/buy. The F8 console shows a 404 or "failed to fetch". Use GetParentResourceName() and keep the callback name identical on both sides.
• Never calling cb. The Lua callback runs, does its work, and returns without cb(...). The fetch promise in JS never resolves and the UI hangs. Always call cb once, even with an empty table.
• Trusting NUI data as if the server validated it. A callback receives { price = 0 } and the client forwards it to the server, which charges zero. NUI callbacks arrive from the client, so the server must look up prices and permissions itself.
• Files missing from files {}. The page loads blank and the F8 console shows a 404 for the stylesheet or the script. Every file the page loads must be listed, including images and fonts.

Why AI assistants get FiveM NUI wrong

Generic assistants mix up the layers. They put SendNUIMessage in a server script, invent a RegisterNUICallback on the server, or write fetch('/callback') with a relative path that the CEF browser cannot resolve. They also treat the callback payload as trusted input and write business logic on the client, which any player can edit.

The FiveM NUI skill gives the assistant a rule file per topic: setup.md for the manifest and folder structure, fullscreen-nui.md for messaging and focus, nui-callbacks.md for the callback contract and its security rules, best-practices.md for performance and error handling, and reference-links.md for the official docs. The assistant reads the matching rule and writes the correct native on the correct side.

Install the FiveM NUI skill in 30 seconds

1. Click "Download SKILL.md" at the top of this page.
2. Unzip it into the skills or rules folder of your AI tool. The install section below shows the exact path for Claude Code, Cursor and VS Code.
3. Ask the assistant for something concrete, like "a fullscreen menu that opens on a command and closes with Escape", and check that it uses SetNuiFocus, RegisterNUICallback with cb, and lists every file in fxmanifest.lua.