GTM UI

GTM UI is a free, shared UI resource for FiveM that gives every resource on your server a unified notification, help-text, and menu system — with a single line of code.

Install it once, call it from any resource via exports. No NUI setup, no event spaghetti.

Features

Three rendering themes — React/NUI overlay, GTA V natives, or your own custom resource
Notifications — info, success, warning, error; optional progress bar; auto-dismiss or manual
Help text — bottom-screen hints with optional auto-hide after a timeout
Menus — fully navigable menus with items, checkboxes, list selectors, separators, submenus, and per-item callbacks via FiveM events
Sound — optional PlaySoundFrontend sound on notification/help-text (configurable)
Newline support — use \n in any text field to break lines
No dependency on any framework — works standalone, with ESX, QBCore, or anything else

Themes

Configure in config.json:

nui — React + Tailwind NUI overlay. Styled toasts, animated menus, <kbd> key badges.
native — Pure FiveM natives and scaleform. No NUI layer required. Works in all situations.
custom — Delegate every UI call to exports of your own choosing.

{
  "UI": {
    "Theme": "nui"
  }
}

Exports

All functionality is exposed as client-side exports from the gtm-ui resource.

`showNotification(options)` → `string`

Shows a notification. Returns the notification ID.

local id = exports['gtm-ui']:showNotification({
  title    = "Payment received",
  message  = "You earned $500.",
  type     = "success",  -- "info" | "success" | "warning" | "error"duration = 5000,       -- ms, default 4000
})

const id = exports['gtm-ui'].showNotification({
  title:    "Payment received",
  message:  "You earned $500.",
  type:     "success",
  duration: 5000,
});

Options:

id (string, optional) — Custom notification ID. Auto-generated if omitted.
title (string, optional) — Bold header line.
message (string) — Body text. Supports \n for line breaks.
type (string, default "info") — "info" · "success" · "warning" · "error"
duration (number, default 4000) — Display time in milliseconds.
position (string, default from config) — NUI only: "top-right" · "top-left" · "bottom-right" · "bottom-left" · "top-center" · "bottom-center"
progress (number, optional) — Initial progress bar value 0–100 (NUI only).

`hideNotification(id)`

Dismisses a notification before its duration expires.

exports['gtm-ui']:hideNotification(id)

`updateProgressNotification(id, progress)`

Updates the progress bar value of an existing notification live (NUI only).

exports['gtm-ui']:updateProgressNotification(id, 75)

id (string) — ID returned by showNotification.
progress (number) — New value, 0–100.

`showHelpText(options)`

Shows a persistent hint at the bottom of the screen. Replaces any existing hint.

exports['gtm-ui']:showHelpText({
  message  = "Press ~INPUT_CONTEXT~ to interact",
  duration = 4000,  -- optional: auto-hide after ms
})

exports['gtm-ui'].showHelpText({
  message:  "Press ~INPUT_CONTEXT~ to interact",
  duration: 4000,
});

Options:

message (string) — Hint text. Supports \n for line breaks.
duration (number, optional) — Auto-hide after this many ms. Omit to keep visible until hideHelpText().
loop (boolean, default true) — Redraw every frame (native theme).
beep (boolean, default false) — Play beep sound (native theme).

`hideHelpText()`

Removes the current help-text hint.

exports['gtm-ui']:hideHelpText()

`isHelpTextActive()` → `boolean`

Returns true if a help-text hint is currently visible.

local active = exports['gtm-ui']:isHelpTextActive()

`openMenu(definition)`

Opens a menu. Keyboard navigation is handled automatically.

After the player interacts, gtm-ui emits local FiveM events — see Events below.

exports['gtm-ui']:openMenu({
  id       = "myresource:shop",
  title    = "Item Shop",
  subtitle = "Select an item",
  items    = {
    { id = "burger", label = "Burger", badge = "$5" },
    { id = "water",  label = "Water",  badge = "$2" },
    { id = "sep1",   label = "",       type  = "separator" },
    {
      id          = "spicy",
      label       = "Spicy Burger",
      badge       = "$8",
      type        = "checkbox",
      checked     = false,
      description = "Extra hot\nContains chilli",
    },
    {
      id         = "size",
      label      = "Size",
      type       = "list",
      listValues = {
        { label = "Small",  value = "s" },
        { label = "Medium", value = "m" },
        { label = "Large",  value = "l" },
      },
      listIndex  = 0,
    },
  },
})

MenuDefinition fields:

id (string) — Unique menu ID. Use namespaced strings, e.g. "myresource:main".
title (string) — Header text.
subtitle (string, optional) — Sub-header text.
items (array) — List of MenuItem objects (see below).
position (string, optional) — NUI only: "top-left" (default) or "top-right".
banner (string, optional) — NUI only: URL to a banner image shown in the header.

MenuItem fields:

id (string) — Unique identifier within this menu.
label (string) — Display label. Supports \n.
type (string, default "item") — "item" · "separator" · "checkbox" · "list"
description (string, optional) — Sub-text shown below the item. Supports \n.
badge (string, optional) — Right-aligned badge (e.g. a price).
disabled (boolean, optional) — Greys out the item; not selectable.
checked (boolean, optional) — checkbox only: initial state.
listValues (array, optional) — list only: array of { label, value } pairs.
listIndex (number, optional) — list only: initially selected index.
icon (string, optional) — NUI only: Lucide icon name (e.g. "car").
color (string, optional) — NUI only: accent colour hex (e.g. "#f97316").
submenu (MenuDefinition, optional) — Opens a sub-menu when this item is selected.

`closeMenu(menuId)`

Closes a menu programmatically.

exports['gtm-ui']:closeMenu("myresource:shop")

`isMenuOpen(menuId?)` → `boolean`

Returns whether a menu is currently open. If menuId is omitted, returns true if any menu is open.

if exports['gtm-ui']:isMenuOpen("myresource:shop") then-- ...end

`getTheme()` → `string`

Returns the active theme: "nui", "native", or "custom".

local theme = exports['gtm-ui']:getTheme()

Events

gtm-ui emits local client events for menu interaction. Listen with AddEventHandler.

`gtm-ui:menuItemSelected`

Fired when the player confirms a plain item or a checkbox.

menuId (string) — The menu's id.
itemId (string) — The item's id.
value (any) — boolean for checkboxes (new state), nil for plain items.

AddEventHandler('gtm-ui:menuItemSelected', function(menuId, itemId, value)if menuId == "myresource:shop" and itemId == "burger" then
    TriggerServerEvent("myresource:buyBurger")
  endend)

`gtm-ui:menuItemChanged`

Fired when the player changes a list value or toggles a checkbox.

menuId (string) — The menu's id.
itemId (string) — The item's id.
value (any) — New listValue.value (list) or boolean (checkbox).
checked (boolean) — Updated checked state for checkboxes, nil for lists.
listIndex (number) — Updated index for list items, nil for checkboxes.

AddEventHandler('gtm-ui:menuItemChanged', function(menuId, itemId, value, checked, listIndex)-- handle changeend)

`gtm-ui:menuClosed`

Fired when a menu is closed (back/escape pressed or closeMenu() called).

menuId (string) — The menu's id.

AddEventHandler('gtm-ui:menuClosed', function(menuId)
  print("Menu closed: " .. menuId)
end)

Configuration

config.json in the resource root:

{
  "UI": {
    "Theme": "nui",
    "Nui": {
      "NotificationPosition": "top-right",
      "NotificationDuration": 4000
    },
    "Sound": {
      "Notification": false,
      "HelpText": false
    },
    "Custom": {
      "NotificationExport": "my_notify:show",
      "HelpTextExport":     "my_helptext:show",
      "MenuExport":         "my_menu:open"
    }
  }
}

Options:

UI.Theme (default "nui") — Active theme: "nui" · "native" · "custom"
UI.Nui.NotificationPosition (default "top-right") — Default toast position (NUI only).
UI.Nui.NotificationDuration (default 4000) — Default toast duration in ms (NUI only).
UI.Sound.Notification (default false) — Play a sound on every notification.
UI.Sound.HelpText (default false) — Play a sound on every help-text.
UI.Custom.NotificationExport — Export reference for notifications, format "resource:export" (custom theme).
UI.Custom.HelpTextExport — Export reference for help-text (custom theme).
UI.Custom.MenuExport — Export reference for menus (custom theme).

License

Free to use on any server. Redistribution and resale are not permitted.
© 2026 Garmingo UG (haftungsbeschränkt) — All rights reserved.