# Functions `[Client]` Reference of all the functions and methods of the menu module. To discover the possibilities of the menu step by step, start with the [Menu](./index) page. ## Constructor ### `[Client]` jo.menu.create() Create a new menu. If a menu with the same ID exists, it's replaced
Add the items with `MenuClass:addItem()`, then send the menu to the NUI with `MenuClass:send()`
#### Syntax ```lua jo.menu.create(id, data) ``` #### Parameters `id` : _string_ > Unique ID of the menu > `data` : _table_ > The menu configuration > > `data.title` : _string_ - The big title of the menu. HTML is allowed
default: `"Jump On"` `[Optional]` > > `data.subtitle` : _string_ - The subtitle of the menu, displayed above the items. HTML is allowed
default: `""` `[Optional]` > > `data.type` : _string_ - The type of menu: `list` or `tile`
default: `"list"` `[Optional]` > > `data.numberOnScreen` : _integer_ - `list` menu: number of items displayed before the scroll. Maximum `13`
default: `8` `[Optional]` > > `data.numberOnLine` : _integer_ - `tile` menu: number of tiles per line
default: `4` `[Optional]` > > `data.numberLineOnScreen` : _integer_ - `tile` menu: number of lines displayed before the scroll
default: `6` `[Optional]` > > `data.image` : _string|table_ - An image displayed above the items: a URL or `{url, width, height, radius, style}` `[Optional]` > > `data.displayBackButton` : _boolean_ - Display the back arrow next to the subtitle, even without history
default: `false` `[Optional]` > > `data.hideBackground` : _boolean_ - Hide the dark background behind the menu
default: `false` `[Optional]` > > `data.price` : _number|table_ - The price displayed when the active item has no price. See [Prices](./items#prices) `[Optional]` > > `data.priceTitle` : _string_ - Replace the "Price" label of `data.price` `[Optional]` > > `data.distanceToClose` : _number_ - The menu closes itself when the player moves further than this distance
default: `false` `[Optional]` > > `data.translateTitle` : _boolean_ - Use `title` as a key of the translation strings
default: `false` `[Optional]` > > `data.translateSubtitle` : _boolean_ - Use `subtitle` as a key of the translation strings
default: `false` `[Optional]` > > `data.onBeforeEnter` : _function_ - Fired before the menu is displayed. The NUI waits for the end of the function `[Optional]` > > `data.onEnter` : _function_ - Fired when the menu becomes the current menu `[Optional]` > > `data.onBack` : _function_ - Fired when Backspace or Escape is pressed `[Optional]` > > `data.onExit` : _function_ - Fired when the menu is no longer the current menu `[Optional]` > > `data.onChange` : _function_ - Fired when the active item or a slider changes in the menu `[Optional]` > > `data.onTick` : _function_ - Fired every frame while the menu is the current menu `[Optional]` > #### Return Value Type : _[MenuClass](#menuclass-methods)_ > The new menu --- ### `[Client]` jo.menu.createIfNotExist() Create a new menu, only if no menu exists with this ID
Returns two values: the menu (the new one or the existing one) and `true` if the menu was created
#### Syntax ```lua jo.menu.createIfNotExist(id, data) ``` #### Parameters `id` : _string_ > Unique ID of the menu > `data` : _table_ > The menu configuration. See [jo.menu.create()](#jo-menu-create) > #### Return Value Type : _[MenuClass](#menuclass-methods)_ > The menu ## MenuClass Methods ### `[Client]` MenuClass:addItem() Add an item to the menu. Call `MenuClass:send()` to send the menu to the NUI
#### Syntax ```lua MenuClass:addItem(index, item) ``` #### Parameters `index` : _integer|table_ > The position of the item in the menu, or the item itself to add it at the end > `item` : _table_ `[Optional]` > The item to add, when `index` is a position > > `item.title` : _string_ - The item label. HTML is allowed > > `item.subtitle` : _string_ - A second line displayed under the title `[Optional]` > > `item.description` : _string_ - The text displayed in the description area, under the list. HTML is allowed `[Optional]` > > `item.footer` : _string_ - The text displayed at the bottom of the menu. HTML is allowed `[Optional]` > > `item.child` : _string_ - The ID of the menu opened when the item is clicked
default: `false` `[Optional]` > > `item.visible` : _boolean_ - If `false`, the item is not displayed
default: `true` `[Optional]` > > `item.disabled` : _boolean_ - Grey out the item: it can't be clicked and its sliders are hidden
default: `false` `[Optional]` > > `item.data` : _table_ - Free storage for your own data, available in the callbacks with `currentData.item.data` `[Optional]` > > `item.icon` : _string_ - The icon on the left of the item: a filename of `nui/menu/assets/images/icons` (without `.png`) or a full image URL `[Optional]` > > `item.iconClass` : _string_ - CSS classes applied to the icon, like `fgold` or `bw`. See [CSS classes](./menus#css-classes) `[Optional]` > > `item.iconSize` : _string_ - `"small"` to reduce the size of the icon
default: `"normal"` `[Optional]` > > `item.iconRight` : _string_ - An icon displayed on the right of the item. In a `tile` menu, it's displayed in the bottom right corner of the tile `[Optional]` > > `item.prefix` : _string_ - A small icon displayed before the title `[Optional]` > > `item.textRight` : _string_ - A text displayed on the right of the item `[Optional]` > > `item.textRightClass` : _string_ - CSS classes applied to `textRight`, like `tiny` `[Optional]` > > `item.image` : _string|table_ - An image displayed in the description area: a URL or `{url, width, height, radius, style}` `[Optional]` > > `item.color` : _string|table_ - The CSS color of the title, or a table `{title, background, accent, icon}`. See [Colors](./items#colors) `[Optional]` > > `item.price` : _number|table_ - The price displayed under the description. See [Prices](./items#prices)
default: `false` `[Optional]` > > `item.priceTitle` : _string_ - Replace the "Price" label above the price `[Optional]` > > `item.priceRight` : _boolean|number|table_ - Display a price on the right of the item: `true` to display `item.price`, or a price value `[Optional]` > > `item.statistics` : _table_ - The list of statistics displayed in the description area. See [Statistics](./statistics) `[Optional]` > > `item.sliders` : _table_ - The list of sliders of the item. See [Sliders](./sliders) `[Optional]` > > `item.previewPalette` : _boolean_ - Display a square with the current color of the sliders on the right of the item
default: `false` `[Optional]` > > `item.quantity` : _number_ - In a `tile` menu, a number displayed in a circle in the top right corner of the tile `[Optional]` > > `item.quantityCircleClass` : _string_ - CSS classes applied to the quantity circle, like `fgold` `[Optional]` > > `item.quality` : _integer_ - In a `tile` menu, a quality from `1` to `3` displayed with stars `[Optional]` > > `item.qualityClass` : _string_ - CSS classes applied to the quality stars `[Optional]` > > `item.stars` : _table_ - In a `tile` menu, a row of stars: `{current, total}` `[Optional]` > > `item.starsClass` : _string_ - CSS classes applied to the row of stars `[Optional]` > > `item.tilePadding` : _number|string_ - In a `tile` menu, the space between the image and the edge of the tile: a number in vh, or a CSS length. `0` brings the image to the edge
default: `1.2` `[Optional]` > > `item.translate` : _boolean_ - Use `title` as a key of the translation strings. See [jo.menu.updateLang()](#jo-menu-updatelang)
default: `false` `[Optional]` > > `item.translateDescription` : _boolean_ - Use `description` as a key of the translation strings
default: `false` `[Optional]` > > `item.translateTextRight` : _boolean_ - Use `textRight` as a key of the translation strings
default: `false` `[Optional]` > > `item.bufferOnChange` : _boolean_ - Wait a few milliseconds between two `onChange` events of fast slider moves. `false` fires them on the next frame
default: `true` `[Optional]` > > `item.onActive` : _function_ - Fired when the item becomes the active item `[Optional]` > > `item.onClick` : _function_ - Fired when the item is clicked or Enter is pressed `[Optional]` > > `item.onChange` : _function_ - Fired when a slider of the item changes `[Optional]` > > `item.onExit` : _function_ - Fired when the item is no longer the active item `[Optional]` > > `item.onTick` : _function_ - Fired every frame while the item is active `[Optional]` > #### Return Value Type : _[MenuItemClass](#menuitemclass-methods)_ > The added item --- ### `[Client]` MenuClass:deleteItem() Delete an item of the menu and update the index of the next items. Call `MenuClass:push()` to send the changes to the NUI
#### Syntax ```lua MenuClass:deleteItem(index) ``` #### Parameters `index` : _integer_ > The index of the item to delete > --- ### `[Client]` MenuClass:deleteValue() Delete a property of the menu or of one of its items. Call `MenuClass:push()` to send the changes to the NUI
`{"items", index}` deletes the item, like `MenuClass:deleteItem()`
#### Syntax ```lua MenuClass:deleteValue(keys) ``` #### Parameters `keys` : _string|table_ > The property name, or the path to a nested property like `{"items", 2, "price"}` > --- ### `[Client]` MenuClass:push() Send to the NUI the changes made with `updateValue()`, `deleteValue()` and `deleteItem()`
#### Syntax ```lua MenuClass:push() ``` --- ### `[Client]` MenuClass:refresh() Send the whole menu to the NUI again, without changing the active item
Use it after big changes, like items added or sorted after `MenuClass:send()`
If the menu is the current menu, `onExit` and `onActive` of the active item are fired again
#### Syntax ```lua MenuClass:refresh() ``` --- ### `[Client]` MenuClass:removeItem() ::: warning DEPRECATED since v2.4.0. Use MenuClass:deleteItem() instead ::: Remove an item from the menu, in Lua only
#### Syntax ```lua MenuClass:removeItem(index) ``` #### Parameters `index` : _integer_ > The index of the item to remove > --- ### `[Client]` MenuClass:reset() Move the cursor of the menu back to the first item
#### Syntax ```lua MenuClass:reset() ``` --- ### `[Client]` MenuClass:send() Send the menu to the NUI. Call it once the items are added
If the menu has already been sent, it's refreshed (see `MenuClass:refresh()`)
#### Syntax ```lua MenuClass:send() ``` --- ### `[Client]` MenuClass:setCurrentIndex() Move the cursor to an item
#### Syntax ```lua MenuClass:setCurrentIndex(index) ``` #### Parameters `index` : _integer_ > The index of the item > --- ### `[Client]` MenuClass:sort() Sort the items alphabetically by title
Call `MenuClass:refresh()` (or `MenuClass:send()` if the menu has never been sent) to display the new order
#### Syntax ```lua MenuClass:sort(first, last) ``` #### Parameters `first` : _integer_ `[Optional]` > The position of the first item to sort
default: `1` > `last` : _integer_ `[Optional]` > The position of the last item to sort
default: the last item > --- ### `[Client]` MenuClass:updateItem() ::: warning DEPRECATED since v2.3.0. Use MenuClass:updateValue() or MenuItem:updateValue() then MenuClass:push() instead ::: Overwrite a property of an item. The NUI is not updated
#### Syntax ```lua MenuClass:updateItem(index, key, value) ``` #### Parameters `index` : _integer_ > The index of the item to update > `key` : _string_ > The property name to update > `value` : _any_ > The new value for the property > --- ### `[Client]` MenuClass:updateValue() Update a property of the menu or of one of its items. Call `MenuClass:push()` to send the changes to the NUI
`price` and `priceRight` values are formatted automatically
#### Syntax ```lua MenuClass:updateValue(keys, value) ``` #### Parameters `keys` : _string|table_ > The property name, or the path to a nested property like `{"items", 2, "title"}` > `value` : _any_ > The new value > #### Return Value Type : _boolean_ > Always `true` --- ### `[Client]` MenuClass:use() Set the menu as the current menu. Same as `jo.menu.setCurrentMenu()`
#### Syntax ```lua MenuClass:use(keepHistoric, resetMenu) ``` #### Parameters `keepHistoric` : _boolean_ `[Optional]` > Keep the previous menu in the history, to go back to it with Backspace
default: `true` > `resetMenu` : _boolean_ `[Optional]` > Move the cursor back to the first item
default: `true` > ## MenuItemClass Methods ### `[Client]` MenuItemClass:deleteValue() Delete a property of the item. Call `MenuClass:push()` to send the changes to the NUI
Only works on an item returned by `MenuClass:addItem()`
#### Syntax ```lua MenuItemClass:deleteValue(keys) ``` #### Parameters `keys` : _string|table_ > The property name, or the path to a nested property like `{"sliders", 2}` > --- ### `[Client]` MenuItemClass:getParentMenu() Get the menu the item belongs to
Only works on an item returned by `MenuClass:addItem()`
#### Syntax ```lua MenuItemClass:getParentMenu() ``` #### Return Value Type : _[MenuClass](#menuclass-methods)_ > The parent menu --- ### `[Client]` MenuItemClass:updateValue() Update a property of the item. Call `MenuClass:push()` to send the changes to the NUI
Only works on an item returned by `MenuClass:addItem()`
#### Syntax ```lua MenuItemClass:updateValue(keys, value) ``` #### Parameters `keys` : _string|table_ > The property name, or the path to a nested property like `{"sliders", 1, "current"}` > `value` : _any_ > The new value > ## Menu Management ### `[Client]` jo.menu.addItem() Add an item to a menu from its ID. Same as `MenuClass:addItem()`
#### Syntax ```lua jo.menu.addItem(id, p, item) ``` #### Parameters `id` : _string_ > The menu ID > `p` : _integer|table_ > The position of the item in the menu, or the item itself to add it at the end > `item` : _table_ `[Optional]` > The item to add, when `p` is a position. See [MenuClass:addItem()](#menuclass-additem) for the keys > --- ### `[Client]` jo.menu.delete() Delete a menu, in Lua and in the NUI
#### Syntax ```lua jo.menu.delete(id) ``` #### Parameters `id` : _string_ > The menu ID > --- ### `[Client]` jo.menu.get() Get a menu from its ID
#### Syntax ```lua jo.menu.get(id) ``` #### Parameters `id` : _string_ > The menu ID > #### Return Value Type : _[MenuClass](#menuclass-methods)_ > The menu object --- ### `[Client]` jo.menu.isExist() Check if a menu exists
#### Syntax ```lua jo.menu.isExist(id) ``` #### Parameters `id` : _string_ > The menu ID > #### Return Value Type : _boolean_ > Returns `true` if the menu exists --- ### `[Client]` jo.menu.refresh() Refresh a menu from its ID. Same as `MenuClass:refresh()`
#### Syntax ```lua jo.menu.refresh(id) ``` #### Parameters `id` : _string_ > The menu ID > --- ### `[Client]` jo.menu.reset() Reset a menu from its ID. Same as `MenuClass:reset()`
#### Syntax ```lua jo.menu.reset(id) ``` #### Parameters `id` : _string_ > The menu ID > --- ### `[Client]` jo.menu.send() Send a menu to the NUI from its ID. Same as `MenuClass:send()`
#### Syntax ```lua jo.menu.send(id) ``` #### Parameters `id` : _string_ > The menu ID > --- ### `[Client]` jo.menu.set() Replace the menu stored with this ID
#### Syntax ```lua jo.menu.set(id, menu) ``` #### Parameters `id` : _string_ > The menu ID > `menu` : _[MenuClass](#menuclass-methods)_ > The menu > --- ### `[Client]` jo.menu.sort() Sort the items of a menu from its ID. Same as `MenuClass:sort()`
#### Syntax ```lua jo.menu.sort(id, first, last) ``` #### Parameters `id` : _string_ > The menu ID > `first` : _integer_ `[Optional]` > The position of the first item to sort
default: `1` > `last` : _integer_ `[Optional]` > The position of the last item to sort
default: the last item > --- ### `[Client]` jo.menu.updateItem() ::: warning DEPRECATED since v2.3.0. Use MenuClass:updateValue() or MenuItem:updateValue() then MenuClass:push() instead ::: Overwrite a property of an item from the menu ID. The NUI is not updated
#### Syntax ```lua jo.menu.updateItem(id, index, key, value) ``` #### Parameters `id` : _string_ > The menu ID > `index` : _integer_ > The index of the item to update > `key` : _string_ > The property name to update > `value` : _any_ > The new value for the property > ## Display ### `[Client]` jo.menu.displayLoader() Display a loading animation in the menu
#### Syntax ```lua jo.menu.displayLoader(value) ``` #### Parameters `value` : _boolean_ `[Optional]` > `false` to hide the loader
default: `true` > --- ### `[Client]` jo.menu.forceBack() Go back to the previous menu of the history, like Backspace
#### Syntax ```lua jo.menu.forceBack() ``` --- ### `[Client]` jo.menu.hideLoader() Hide the loading animation
#### Syntax ```lua jo.menu.hideLoader() ``` --- ### `[Client]` jo.menu.isOpen() Check if the menu is displayed
#### Syntax ```lua jo.menu.isOpen() ``` #### Return Value Type : _boolean_ > Returns `true` if the menu is displayed --- ### `[Client]` jo.menu.isSoftHidden() Check if the menu is hidden by `jo.menu.softHide()`
#### Syntax ```lua jo.menu.isSoftHidden() ``` #### Return Value Type : _boolean_ > Returns `true` during the execution of the `jo.menu.softHide()` function --- ### `[Client]` jo.menu.setCurrentMenu() Set the current menu: the one displayed by `jo.menu.show()`
If the menu doesn't exist, the handler registered with `jo.menu.missingMenuHandler()` is called
#### Syntax ```lua jo.menu.setCurrentMenu(id, keepHistoric, resetMenu) ``` #### Parameters `id` : _string_ > The menu ID > `keepHistoric` : _boolean_ `[Optional]` > Keep the previous menu in the history, to go back to it with Backspace
default: `true` > `resetMenu` : _boolean_ `[Optional]` > Move the cursor back to the first item
default: `true` > --- ### `[Client]` jo.menu.show() Show or hide the current menu
While the menu is displayed, the radar is hidden and the weapon wheel and pause menu controls are disabled
#### Syntax ```lua jo.menu.show(show, keepInput, hideRadar, playMenuAnimation, hideCursor) ``` #### Parameters `show` : _boolean_ > `true` to show the menu, `false` to hide it > `keepInput` : _boolean_ `[Optional]` > Keep the game controls active, to move the player while the menu is open
default: `true` > `hideRadar` : _boolean_ `[Optional]` > Unused: the radar is always hidden while the menu is displayed
default: `true` > `playMenuAnimation` : _boolean_ `[Optional]` > Play the open/close animation
default: `true` > `hideCursor` : _boolean_ `[Optional]` > Hide the mouse cursor
default: `false` > --- ### `[Client]` jo.menu.softHide() Hide the menu during the execution of a function, then display it again
The function is executed synchronously: `jo.menu.softHide()` returns once the menu is displayed again
#### Syntax ```lua jo.menu.softHide(cb, playMenuAnimation, keepBackground) ``` #### Parameters `cb` : _function_ > The function executed while the menu is hidden > `playMenuAnimation` : _boolean_ `[Optional]` > Play the open/close animation
default: `true` > `keepBackground` : _boolean_ `[Optional]` > Keep the dark background of the menu while it's hidden
default: `false` > ## Current State ### `[Client]` jo.menu.doesActiveButtonChange() Check if the active item (or the menu) changed during the last update
Useful in `onChange` callbacks, to know if a slider moved or if the cursor moved
#### Syntax ```lua jo.menu.doesActiveButtonChange() ``` #### Return Value Type : _boolean_ > Returns `true` if the active item changed --- ### `[Client]` jo.menu.getCurrentData() Get the current state of the menu: the data passed to all the callbacks
#### Syntax ```lua jo.menu.getCurrentData() ``` #### Return Value Type : _table_ > `{menu = menuID, index = activeItemIndex, item = activeItem}` --- ### `[Client]` jo.menu.getCurrentIndex() Get the index of the active item of the current menu
#### Syntax ```lua jo.menu.getCurrentIndex() ``` #### Return Value Type : _integer_ > The index of the active item --- ### `[Client]` jo.menu.getCurrentItem() Get the active item of the current menu
#### Syntax ```lua jo.menu.getCurrentItem() ``` #### Return Value Type : _[MenuItemClass](#menuitemclass-methods)_ > The active item --- ### `[Client]` jo.menu.getCurrentMenu() Get the current menu
#### Syntax ```lua jo.menu.getCurrentMenu() ``` #### Return Value Type : _[MenuClass](#menuclass-methods)_ > The current menu --- ### `[Client]` jo.menu.getCurrentMenuId() Get the ID of the current menu
#### Syntax ```lua jo.menu.getCurrentMenuId() ``` #### Return Value Type : _string_ > The ID of the current menu --- ### `[Client]` jo.menu.getPreviousData() Get the state of the menu before the last change
#### Syntax ```lua jo.menu.getPreviousData() ``` #### Return Value Type : _table_ > `{menu = menuID, index = activeItemIndex, item = activeItem}` --- ### `[Client]` jo.menu.isCurrentMenu() Check if a menu is the current menu and is displayed
#### Syntax ```lua jo.menu.isCurrentMenu(id) ``` #### Parameters `id` : _string_ > The menu ID > #### Return Value Type : _boolean_ > Returns `true` if the menu is displayed and is the current one ## Events ### `[Client]` jo.menu.fireAllLevelsEvent() Fire an event on the current menu, then on its active item
#### Syntax ```lua jo.menu.fireAllLevelsEvent(eventName, ...) ``` #### Parameters `eventName` : _string_ > The name of the event, like `onTick` > `...` : _any_ `[Optional]` > Additional arguments for the listeners > --- ### `[Client]` jo.menu.fireEvent() Fire an event of a menu or an item
The listeners receive the current data (see `jo.menu.getCurrentData()`) followed by the additional arguments
The client and server events defined with `ClientEvent` and `ServerEvent` keys are triggered too
#### Syntax ```lua jo.menu.fireEvent(item, eventName, ...) ``` #### Parameters `item` : _table_ > The menu or the item > `eventName` : _string_ > The name of the event, like `onClick` > `...` : _any_ `[Optional]` > Additional arguments for the listeners > --- ### `[Client]` jo.menu.missingMenuHandler() Register a function to create a menu the first time it's needed
Called when `jo.menu.setCurrentMenu()` or an item `child` targets this menu ID and the menu doesn't exist
#### Syntax ```lua jo.menu.missingMenuHandler(id, callback) ``` #### Parameters `id` : _string_ > The menu ID > `callback` : _function_ > The function that creates the menu > --- ### `[Client]` jo.menu.onChange() Listen to all the changes of all the menus: active item, sliders, menu
The callback receives `{menu, index, item}`. It's unregistered when the resource stops
#### Syntax ```lua jo.menu.onChange(cb) ``` #### Parameters `cb` : _function_ > The function fired on each change > --- ### `[Client]` jo.menu.runRefreshEvents() Fire the events of the current menu again, as if it was just opened
#### Syntax ```lua jo.menu.runRefreshEvents(menuEvent, itemEvent) ``` #### Parameters `menuEvent` : _boolean_ `[Optional]` > Fire `onExit` and `onEnter` of the menu, and `onExit` and `onActive` of the item
default: `false` > `itemEvent` : _boolean_ `[Optional]` > Fire `onExit` and `onActive` of the active item
default: `false` > ## Settings ### `[Client]` jo.menu.playAudio() Play a sound of the menu
#### Syntax ```lua jo.menu.playAudio(sound) ``` #### Parameters `sound` : _string_ > The sound name: `button`, `coins`, `menu_open`, `menu_close` or `selected` > --- ### `[Client]` jo.menu.updateLang() Translate the texts of the menu
You can also add your own keys, used by the `translate*` options of the menus, items and sliders
#### Syntax ```lua jo.menu.updateLang(lang) ``` #### Parameters `lang` : _table_ > The translated strings, by key > > `lang.of` : _string_ - The counter of the items and sliders. `%1` is the current position, `%2` the total
default: `"%1 of %2"` `[Optional]` > > `lang.price` : _string_ - The label above the price
default: `"Price"` `[Optional]` > > `lang.devise` : _string_ - The currency symbol
default: `"$"` `[Optional]` > > `lang.free` : _string_ - The text displayed when the price is `0`
default: `"Free"` `[Optional]` > > `lang.number` : _string_ - The title of an item without title. `%1` is the item position
default: `"Number %1"` `[Optional]` > --- ### `[Client]` jo.menu.updateVolume() Set the volume of the menu sounds
#### Syntax ```lua jo.menu.updateVolume(volume) ``` #### Parameters `volume` : _number_ > The volume, from `0.0` to `1.0`
default: `0.5` >