HUD Layouts

Overview

A HUD layout is a self-contained HTML file plus assets in a folder under layouts/. Lua pushes vehicle state to the NUI every tick, and the layout binds DOM elements to state fields with data-hud-* attributes. Lua does no presentation logic — the layout decides how to display what it receives.

Folders in layouts/ are auto-discovered by the server and appear in the HUD Layout selector in /tels.

Create a layout

layouts/MyLayout/
  ui.html
  icons/       PNG / SVG assets
  sounds/      On.ogg, Off.ogg, Press.ogg (optional)

Data bindings

Attach data-hud-* attributes to DOM elements. The binder processes them on every update.

Use dot paths for nested state: leds.R1 resolves to state.leds.R1.

Example

<div data-hud-show="inVehicle">
  <span data-hud-text="patternName">—</span>
  <div data-hud-led="sirenOn" class="indicator">SIREN</div>
  <div data-hud-eq="taMode:left" class="arrow">◄</div>
  <div data-hud-led-color="leds.R1" class="pip"></div>
  <button data-hud-btn="cycle_pattern">Next</button>
</div>

Available state keys

Lua sends raw data only — no derived strings or presentation. Every key below is optional: the binder only sends keys the layout references (via data-hud-* attributes or data-hud-keys).

Core

Pattern

Siren

Modes

Vehicle

Lights

Controls

Signals

Doors

LEDs

Bind individual LEDs with data-hud-led-color="leds.<name>". The LED colors stream at roughly 20 Hz, independent of the full state update.

Layout scripts

For derived values, dynamic HTML, or anything beyond simple bindings, add a <script data-hud-script> block. The script registers a callback that runs after each binder pass.

<script data-hud-script>
(function () {
  window.__telsLayoutUpdate = function (state, root) {
    // state: raw data from Lua
    // root:  this layout's container element

    var el = root.querySelector('.reverse-indicator');
    if (el) el.style.display = state.reverse ? '' : 'none';

    var kphEl = root.querySelector('.speed-kph');
    if (kphEl) kphEl.textContent = Math.round((state.speedMph || 0) * 1.609);
  };

  // Optional cleanup when the layout is unloaded.
  window.__telsLayoutDestroy = function () {
    // cancel timers, detach listeners, etc.
  };
})();
</script>

Declaring extra data

Lua only sends keys the layout references in data-hud-* attributes. If a script needs a key that isn't bound to any attribute, declare it with data-hud-keys:

<div data-hud-keys="sirenTones,maxStage,sirenTone">
  …
</div>

Without this, Lua skips computing those keys and your script receives undefined.

Buttons

data-hud-btn="<action>" fires a tels:hudButton client event with the action string:

AddEventHandler("tels:hudButton", function(action)
  if action == "cycle_pattern" then
    ExecuteCommand("+lbar_pattern")
  end
end)

Wire it to your own handlers in a separate resource, or reuse the built-in ones.

Sounds

Optional sounds/ folder. The HUD plays:

• On.ogg — on toggle-on actions
• Off.ogg — on toggle-off actions
• Press.ogg — on button press

File paths resolve relative to the layout folder: layouts/<name>/sounds/<file>.ogg.

Browser preview

You can preview layouts in a regular browser without launching FiveM by including the devtools script:

<script src="../devtools.js"></script>

It injects a floating control panel with toggles and sliders for every state key. The script detects the NUI environment and is a no-op when running in-game.

Build devtools from the resource root: bun run build.

Performance notes

• Lua only computes keys the active layout references. data-hud-* attributes and data-hud-keys together drive this filter.
• Full state updates run at ~5 Hz. LED colors (leds.*) update separately at ~20 Hz.
• Cache query selectors in your script closure — it runs on every tick.