Menu

A Menu is one menu: a banner, a subtitle bar, a list of menu items, a description box and optional instructional buttons.

Every menu must be registered with the MenuController, which draws it and handles its controls. Bind a menu to a MenuItem of another menu to make that item a submenu button.

Events (OnItemSelect, OnCheckboxChange, etc.) are members of this class and are documented on the Events page.

Example usageCopy Anchor Link

using MenuAPI;

// Create a menu with a banner title and a subtitle.
Menu menu = new Menu("Main Menu", "Subtitle");

// Register the menu. The first menu you register automatically becomes
// MenuController.MainMenu, which is the menu that the toggle key opens.
MenuController.AddMenu(menu);

// Add some items to it.
menu.AddMenuItem(new MenuItem("Normal Button", "A simple button with a description."));
menu.AddMenuItem(new MenuCheckboxItem("Checkbox", "A checkbox.", true));

// Listen for button presses.
menu.OnItemSelect += (_menu, _item, _index) =>
{
    Debug.WriteLine($"'{_item.Text}' was pressed (index {_index}).");
};

// Open the menu whenever you want.
menu.OpenMenu();

Creating a submenuCopy Anchor Link

Menu menu = new Menu("Main Menu", "Subtitle");
MenuController.AddMenu(menu);

// A submenu is just another Menu. Use AddSubmenu instead of AddMenu so the
// parent/child relation is set up for you (this is what makes 'back' work).
Menu submenu = new Menu("Submenu", "Secondary Menu");
MenuController.AddSubmenu(menu, submenu);

// Create the item that opens the submenu, then bind the two together.
MenuItem submenuButton = new MenuItem("Open submenu", "This opens the submenu.")
{
    Label = "→→→"
};
menu.AddMenuItem(submenuButton);
MenuController.BindMenuItem(menu, submenu, submenuButton);

// Pressing the back/cancel control in the submenu now returns to `menu`.
submenu.AddMenuItem(new MenuItem("I'm inside the submenu!"));

ConstructorsCopy Anchor Link

Menu(string name)Copy Anchor Link

Creates a menu with only a banner title.

Menu(string name, string subtitle)Copy Anchor Link

Creates a menu with a banner title and a subtitle.

// With a banner and a subtitle.
Menu menu = new Menu("Main Menu", "Subtitle");

// With a banner only.
Menu menu2 = new Menu("Main Menu");

// Without a banner, only a subtitle.
Menu menu3 = new Menu(null, "Only a subtitle, no banner.");

PropertiesCopy Anchor Link

ConstantsCopy Anchor Link

MethodsCopy Anchor Link

Methods below return nothing unless a return value is listed.

SetMaxItemsOnScreen(int max)Copy Anchor Link

Sets how many items are visible at once, clamped between 3 and 10. If the resolution is too small for that many, fewer are shown so the menu never runs off screen.

// Only show 5 items at a time.
menu.SetMaxItemsOnScreen(5);

RefreshIndex()Copy Anchor Link

Highlights the first item and scrolls back to the top.

RefreshIndex(int index)Copy Anchor Link

Highlights the item at index and scrolls it into view.

RefreshIndex(int index, int viewOffset)Copy Anchor Link

Highlights the item at index and makes the item at viewOffset the first one on screen.

// Rebuild the menu, but keep the user roughly where they were.
int index = menu.CurrentIndex;
int offset = menu.ViewIndexOffset;

menu.ClearMenuItems();
BuildItems(menu);

menu.RefreshIndex(index, offset);

AddMenuItem(MenuItem item)Copy Anchor Link

Adds an item to the bottom and sets its ParentMenu to this menu.

InsertMenuItem(int index, MenuItem item)Copy Anchor Link

Adds an item at index. The highlighted item stays highlighted, even when the new item lands above it. In a paginated menu the highlight stays at the same spot on the page instead.

The index counts every item, including those a filter hides. An index past the end adds to the bottom. If a filter is active, the new item is not part of it until you call FilterMenuItems() again.

MoveMenuItem(MenuItem item, int index)Copy Anchor Link

Moves an item already in this menu. Unlike remove and add, a submenu button stays bound to its submenu. The highlighted item stays highlighted, except in a paginated menu. An active filter is updated too.

The index counts every item, including those a filter hides. Does nothing if the item is not in this menu.

RemoveMenuItem(int itemIndex)Copy Anchor Link

Removes the item at the index and corrects the current index so the highlight does not jump. Does nothing if the index is out of range.

RemoveMenuItem(MenuItem item)Copy Anchor Link

Removes the item and clears its ParentMenu. Does nothing if the item is not in this menu. A submenu button keeps its submenu, as above.

ClearMenuItems()Copy Anchor Link

Removes all items and resets the index and scroll position. Submenus of the removed buttons are kept, so you can bind new buttons to them.

ClearMenuItems(bool dontResetIndex)Copy Anchor Link

Same as ClearMenuItems(), but can keep the index and scroll position, for rebuilding an open menu.

// Rebuild the items without the menu jumping back to the top.
menu.ClearMenuItems(true);
BuildItems(menu);

GetMenuItems()Copy Anchor Link

Returns the items, only the filtered ones when a filter is active. The list is a copy, so changing it does not change the menu.

// Toggle the 'enabled' state of every item in the menu.
menu.GetMenuItems().ForEach(item => item.Enabled = !item.Enabled);

GetCurrentMenuItem()Copy Anchor Link

SelectItem(int index)Copy Anchor Link

Selects the item at index as if the user pressed select on it. Disabled items play the error sound, submenu buttons open their submenu.

SelectItem(MenuItem item)Copy Anchor Link

Selects the item as if the user pressed select on it.

OpenMenu()Copy Anchor Link

Shows this menu and fires OnMenuOpen.

CloseMenu()Copy Anchor Link

Hides this menu and fires OnMenuClose.

GoBack()Copy Anchor Link

Closes this menu and opens its parent, or just closes if there is none.

GoUp()Copy Anchor Link

Moves the highlight up one, wrapping to the bottom, and fires OnIndexChange. Does nothing if the menu is hidden or has fewer than 2 items.

GoDown()Copy Anchor Link

Moves the highlight down one, wrapping to the top, and fires OnIndexChange. Does nothing if the menu is hidden or has fewer than 2 items.

GoLeft()Copy Anchor Link

Moves a list, dynamic list or slider item left. On other items it goes to the parent menu if MenuController.NavigateMenuUsingArrows is on. In a paginated menu, other items go to the previous page instead.

GoRight()Copy Anchor Link

Moves a list, dynamic list or slider item right. Other items are selected. In a paginated menu, other items go to the next page instead.

SortMenuItems(Comparison<MenuItem> compare)Copy Anchor Link

Sorts the items. Any active filter is cleared first.

// Sort all items alphabetically by their text.
menu.SortMenuItems((a, b) => a.Text.ToLower().CompareTo(b.Text.ToLower()));

FilterMenuItems(Func<MenuItem, bool> predicate)Copy Anchor Link

Hides every item for which the predicate returns false and resets the index and scroll position. Calling it again replaces the previous filter. Hidden items are not removed, but Size and GetMenuItems() only report the visible ones.

// Only show items that are enabled.
menu.FilterMenuItems(item => item.Enabled);

// Or use ItemData to filter on your own data.
menu.FilterMenuItems(item => item.ItemData?.category == "vehicles");

// Show everything again.
menu.ResetFilter();

ResetFilter()Copy Anchor Link

Clears the filter so all items show again, and resets the index.

SetWeaponStats(float damage, float fireRate, float accuracy, float range)Copy Anchor Link

Sets the weapon stats panel values, each clamped between 0 and 1. See Weapon & vehicle stats panels.

SetWeaponComponentStats(float damage, float fireRate, float accuracy, float range)Copy Anchor Link

Sets the attachment bonus per stat. Each value is added on top of the matching SetWeaponStats() value, the total is clamped between 0 and 1, and the added part is drawn in another colour. Negative values make a stat worse.

SetVehicleStats(float topSpeed, float acceleration, float braking, float traction)Copy Anchor Link

Sets the vehicle stats panel values, each clamped between 0 and 1. See Weapon & vehicle stats panels.

SetVehicleUpgradeStats(float topSpeed, float acceleration, float braking, float traction)Copy Anchor Link

Sets the upgrade bonus per stat. Each value is added on top of the matching SetVehicleStats() value, the total is clamped between 0 and 1, and the added part is drawn in blue. A top speed of 0.5 plus 0.2 here shows 0.7 with the last 0.2 in blue. Negative values are downgrades.

Header stylingCopy Anchor Link

You can change the banner title's font, its alignment, and whether GTA Online's moving glow is drawn. This only affects the banner, not the subtitle bar, counter or items.

Each property is nullable. Null uses the MenuController default, so you can style all menus at once and override per menu.

The title fontCopy Anchor Link

MenuTitleFont is a game font id. The useful ones are in MenuFont:

Menu menu = new Menu("Los Santos Customs", "Vehicle mods")
{
    MenuTitleFont = MenuFont.Pricedown
};

Only these five ids are styled. Any other id falls back to the item font at item size, so the title comes out small. Size and vertical offset are set per font, so there is nothing to tune.

Where the title sitsCopy Anchor Link

This is separate from MenuController.MenuAlignment, which picks the side of the screen. A right aligned menu with a left aligned title puts the title at the left of that menu's banner.

menu.MenuTitleAlignment = Menu.TitleAlignmentOption.Left;

The header glareCopy Anchor Link

ShowHeaderGlare draws GTA Online's mp_menu_glare glow, which drifts as the camera turns.

Menu menu = new Menu("Nightclub", "Management")
{
    MenuTitleFont = MenuFont.Pricedown,
    ShowHeaderGlare = true
};

The page draws it with glare.min.js. If it never shows, check that glare.min.js is in your index.html, see How menus are drawn.

Weapon & vehicle stats panelsCopy Anchor Link

Both panels are the game's shop panels, drawn under the description box. A menu with a stats panel enabled should have at least one item.

// Weapon stats panel
Menu weaponMenu = new Menu("Weapon Stats", "Weapon Stats Panel") { ShowWeaponStatsPanel = true };
weaponMenu.AddMenuItem(new MenuItem("Buy weapon", "You should add at least one item when using stat panels."));
weaponMenu.SetWeaponStats(0.2f, 0.4f, 0.7f, 0.8f);
weaponMenu.SetWeaponComponentStats(0.4f, 0f, -0.05f, 0.1f);
MenuController.AddSubmenu(menu, weaponMenu);

// Vehicle stats panel
Menu vehicleMenu = new Menu("Vehicle Stats", "Vehicle Stats Panel") { ShowVehicleStatsPanel = true };
vehicleMenu.AddMenuItem(new MenuItem("Buy vehicle", "You should add at least one item when using stat panels."));
vehicleMenu.SetVehicleStats(0.2f, 0.2f, 0.3f, 0.8f);
vehicleMenu.SetVehicleUpgradeStats(0.4f, -0.025f, 0.05f, 0.1f);
MenuController.AddSubmenu(menu, vehicleMenu);

Instructional buttonsCopy Anchor Link

The button hints in the bottom right. Each menu has its own set, and they switch instantly between keyboard and controller.

They are drawn on your NUI page, just like the menu itself, so a theme can recolour them. You do not have to change your index.html for them, menuapi.js adds them to the page by itself.

Need hints that are not tied to a menu, or that stay up after it closes? Use GlobalInstructionalButtons.

Every menu has select and back, plus change value while the highlighted row is a list, dynamic list or slider (not when it is disabled). All three follow the player's key bindings. Give AddKeyBinding() a buttonText to add a hint for your own key, which follows the bindings too.

// Change the text next to the built in buttons.
menu.SelectButtonText = "Buy";
menu.BackButtonText = "Nevermind";
menu.ChangeValueButtonText = "Pick a colour";

// Hide the built in 'back' button.
menu.ShowBackInstructionalButton = false;

// Add your own, by registering a key for it. This one is rebindable like everything else.
menu.AddKeyBinding("check", "Example: check something", "E", "R1_INDEX",
    handler: (m, b) => Check(),
    buttonText: "Check");

// Or turn them all off for this menu and draw your own.
menu.EnableInstructionalButtons = false;

Draw order: select and back, then change value (or the page hints on other rows of a paginated menu), then key bindings with a buttonText, then CustomInstructionalButtons.

InstructionalButtonCopy Anchor Link

For hints MenuAPI knows nothing about, such as a button combination, add a raw button string to CustomInstructionalButtons.

A button string is a list of icons with a % between each one. It works the same way as in the game itself, which means it is read from right to left: the last icon in the string is drawn first. Put b_998 between two icons to draw a + between them.

string up = GetControlInstructionalButton(0, (int)Control.FrontendUp, 1);
string down = GetControlInstructionalButton(0, (int)Control.FrontendDown, 1);

// Shows the up and down buttons, in that order, with the text 'Move'.
menu.CustomInstructionalButtons.Add(new Menu.InstructionalButton($"{down}%{up}", "Move"));

// Shows 'up + down', for two buttons that have to be pressed together.
menu.CustomInstructionalButtons.Add(new Menu.InstructionalButton($"{down}%b_998%{up}", "Both"));

On Enhanced the third parameter of GetControlInstructionalButton is a bool, so pass true instead of 1.

An icon MenuAPI does not recognise is left out, just like the game does. To find out which one it was, type nui_devtools in the F8 console and look at the console of your resource's page.

Key bindingsCopy Anchor Link

A menu can listen for its own keys without a tick function. Each is a real FiveM key mapping, so players can rebind it under Settings, Key Bindings. Handlers only run while the menu is open and MenuController.DisableMenuButtons is false.

AddKeyBinding()Copy Anchor Link

public KeyBindingHandler AddKeyBinding(
    string name,
    string description,
    string keyboardKey,
    string? controllerButton = null,
    MenuKeyPressType pressType = MenuKeyPressType.JUST_RELEASED,
    Action<Menu, MenuKeyBinding>? handler = null,
    string? buttonText = null)

// Toggle the 'enabled' state of every item whenever this key is released.
menu.AddKeyBinding(
    "toggleitems",
    "Example: toggle every item",
    "K",
    "R1_INDEX",
    MenuKeyPressType.JUST_RELEASED,
    (m, b) => m.GetMenuItems().ForEach(item => item.Enabled = !item.Enabled),
    "Toggle all");

MenuKeyPressTypeCopy Anchor Link

MenuKeyBindingCopy Anchor Link

The key, passed to your handler and available as KeyBindingHandler.Binding.

KeyBindingHandlerCopy Anchor Link

Returned by AddKeyBinding().

EventsCopy Anchor Link

All menu events are documented on the Events page.