PopupMenu in Godot – Complete Guide

Creating menus and options for your game or application can significantly impact the user experience. Whether you’re building a sophisticated strategy game or a simple app, the way users navigate and interact with various functions is critical. This is where the PopupMenu class in Godot 4 comes into play; it’s a robust and flexible way to present choices and actions to the user. Let’s dive in and unlock the potentials of PopupMenu and see how it can make a difference in your projects.

What is PopupMenu in Godot 4?

At its core, the PopupMenu is a specialized modal window that presents a list of clickable options to the user. You can consider it a Swiss army knife for in-game menus, context menus, dropdowns, and toolbars. It’s a subclass of the Popup class, which means it benefits from all the modal behavior that comes with popups, including the ability to grab focus and prevent interaction with other UI elements until an option is selected or the popup is dismissed.

Why Use PopupMenu?

The PopupMenu is essential for creating engaging and intuitive user interfaces within your Godot applications because it:

  • Improves navigation with a clear and organized display of options.
  • Enhances user interaction with a game or application by providing context-specific choices.
  • Supports icons, shortcuts, checks, and radio buttons to cater to various UI requirements.
  • Can dynamically adjust to content, with scrollable options if the list is too long.

Learning how to effectively use PopupMenu will empower you to create more professional and polished projects, setting your work apart in the Godot community.

CTA Small Image

Creating a Basic PopupMenu

To start with PopupMenu in Godot 4, you need to create a new PopupMenu node. This can be done through the editor or via code. Here’s an example of how you can create and show a PopupMenu through GDScript:

var menu = PopupMenu.new()
menu.add_item("Option 1", 0)
menu.add_item("Option 2", 1)
menu.popup_centered(Vector2(200, 100))  # Size of the PopupMenu

This will result in a PopupMenu with two options, “Option 1” and “Option 2”, which pops up at the center of the screen with the specified size.

Connecting Signals

One of the main features of the PopupMenu is the ability to respond to user actions via signals. For instance, when an item is selected, the id_pressed signal is emitted. Here’s how you connect a method to this signal:

menu.connect("id_pressed", self, "_on_menu_item_selected")

func _on_menu_item_selected(id):
    print("Selected option with ID: ", id)

Now, when an item is clicked, it will print the ID of the selected option to the console.

Customizing Menu Items

PopupMenu provides various methods to further customize your menu. For example, you can add a separator between items or insert an icon next to an item:

# Adding a separator

# Adding an item with an icon
var icon = preload("res://path_to_icon.png")
menu.add_icon_item(icon, "Option with Icon", 2)

These features allow you to create a more visually appealing and organized menu structure.

Managing Item Visibility and Availability

Sometimes, you might want to hide certain menu items or make them disabled depending on the context of your game. This is how you can manage the visibility and availability of PopupMenu items:

# Hiding an item
menu.set_item_visible(1, false) # The first argument is the ID of the item

# Disabling an item
menu.set_item_disabled(1, true)  # The first argument is the ID of the item

With this, you can show or hide options dynamically, such as context-sensitive actions that only appear when relevant.

Responding to Right-Clicks with PopupMenu

You often want a context menu to appear when the user right-clicks on a certain area. Here we’ll connect a PopupMenu to appear when the right mouse button is pressed:

func _on_RightClickableArea_gui_input(event):
    if event is InputEventMouseButton and event.button_index == BUTTON_RIGHT and event.pressed:
        menu.popup_centered_maybe_ratio(size)  # Adjust size as needed

This snippet assumes you have an area defined that the user can right-click on, and that the PopupMenu has been properly instantiated as ‘menu’.

These basics set the foundation for creating interactive and user-friendly PopupMenus in your Godot apps and games. In the next section, we’ll explore more advanced examples and techniques to make your PopupMenus stand out.

Let’s delve deeper into advanced features and customization options of the PopupMenu in Godot 4. These will enrich your user interfaces and provide a more dynamic experience.

# Example of how to implement a toggle item
var is_item_toggled = true
menu.add_check_item("Toggle Item", 3)
menu.set_item_checked(3, is_item_toggled)

func _on_menu_item_selected(id):
    if id == 3:
        is_item_toggled = !is_item_toggled
        menu.set_item_checked(3, is_item_toggled)

Using add_check_item creates a toggleable menu item that users can turn on or off. This is ideal for settings or options that can be enabled or disabled within your game or application.

If your menu is context-sensitive, you might also need to change its position depending on where the user clicks. The following code allows your PopupMenu to appear at the mouse cursor’s position.

func _input(event):
    if event is InputEventMouseButton and event.button_index == BUTTON_RIGHT and event.pressed:

Creating submenus is another feature that can help organize options hierarchically, making extensive menus more navigable.

# Adding a submenu to the main menu
var submenu = menu.get_popup_submenu(4)
submenu.add_item("Submenu Item 1", 5)
submenu.add_item("Submenu Item 2", 6)
menu.add_submenu_item("Advanced", "Submenu", 4)

Setting up radio button groups is useful for options where only one item can be selected out of a set of choices. Radio items are another way to manage exclusive choices within PopupMenu.

menu.add_radio_check_item("Radio Item 1", 7)
menu.add_radio_check_item("Radio Item 2", 8)
menu.set_item_as_radio_check_item(7, true)
menu.set_item_as_radio_check_item(8, true)

# Set the group to which radio check items belong
menu.set_item_radio_check_group(7, 0)
menu.set_item_radio_check_group(8, 0)

# Select the default choice
menu.set_item_checked(7, true)

func _on_menu_item_selected(id):
    if id == 7 or id == 8:
        # Uncheck all other items in the group
        for i in range(menu.get_item_count()):
            if menu.get_item_radio_check_group(i) == 0 and i != id:
                menu.set_item_checked(i, false)

Remember that radio check items need to belong to the same group to ensure that selecting one will uncheck the others in the group.

Lastly, customization is not limited to functionality. You can also change the look of your PopupMenu items with styles and themes.

# Change font color of a specific item
var custom_color = Color(1, 0, 0) # Red color
menu.set_item_custom_color(0, custom_color)

# Change the font of all items
var custom_font = preload("res://path_to_font.tres")
menu.add_font_override("font", custom_font)

Utilizing these advanced features allows for a more refined and powerful user interface that caters to a variety of contexts within your Godot projects. By learning and applying these different customization options, you will be able to create PopupMenus that are not only functional but also fit the aesthetic and interactivity of your game or app beautifully.Continuing with the advanced features of the PopupMenu in Godot 4, let’s explore how we can integrate shortcuts, dynamic item insertion, and the handling of events for complex UI interactions.

To associate shortcuts with menu items, you can create InputEventKey instances and use them to make keyboard shortcuts for your options:

# Define a shortcut for Option 1 using the S key
var shortcut = InputEventKey.new()
shortcut.scancode = KEY_S
menu.set_item_shortcut(0, shortcut, true)

This code snippet assigns a shortcut to the first item in your PopupMenu. Now pressing the ‘S’ key will trigger the same action as clicking ‘Option 1’.

PopupMenu’s flexibility allows you to insert items dynamically based on the game’s state or user interaction. For instance, you can insert an item at a specific position or remove items:

# Insert an item at the second position
menu.add_item("New Dynamic Option", 9)
menu.set_item_position(9, 1)

# Remove an item based on its ID

Handling events for items within submenus can be slightly more involved since you will need to connect signals from the submenu as well:

# Ensure to properly instance your submenu
var submenu = PopupMenu.new()
menu.set_submenu("Submenu", submenus)

# Connect submenu signals
submenu.connect("id_pressed", self, "_on_submenu_item_selected")

func _on_submenu_item_selected(id):
    print("Submenu option with ID: ", id)

Another interesting feature is enabling multiple selections within a PopupMenu through checkboxes, providing a way for users to select several options:

# Allow multiple selections
menu.add_check_item("Check Item 1", 10)
menu.add_check_item("Check Item 2", 11)

# Initialize them as checked
menu.set_item_checked(10, true)
menu.set_item_checked(11, true)

Creating a confirmation dialogue within your menu can be beneficial for actions that could have significant effects or should not be easily reversible:

# Add a potentially impactful action with a confirmation step
menu.add_item("Reset Game", 12)
menu.connect("id_pressed", self, "_on_reset_game_selected")

func _on_reset_game_selected(id):
    if id == 12:
        # Show a confirmation dialog before resetting
        confirmation_dialog.connect("confirmed", self, "_reset_game")

func _reset_game():
    # Code to reset the game

Lastly, remember that you can always animate the PopupMenu for a more engaging user experience:

# Fade-in animation for the popup menu
menu.modulate = Color(1, 1, 1, 0) # Set initial transparency to fully transparent
menu.tween_interpolate_property(menu, "modulate", 
    Color(1, 1, 1, 0), Color(1, 1, 1, 1), 0.5,

With these added functionalities and code snippets, it’s clear that PopupMenu in Godot 4 allows for a robust and dynamic approach to UI development. Whether it’s a complex in-game strategy menu or a simple settings dropdown, PopupMenu equips you with the tools necessary to create a responsive and thoughtful user interface. By understanding and utilizing these advanced features, your applications and games will become more intuitive and engaging for the user.

Where to Go Next with Your Godot 4 Journey

Mastering the PopupMenu class is a significant step in becoming proficient with Godot 4’s UI tools. But your learning journey doesn’t have to end here! To keep expanding your game development skills and uncover the full potential of Godot 4, we invite you to explore our Godot Game Development Mini-Degree. This comprehensive collection of courses is designed to guide you through various aspects of game development, from 2D and 3D essentials to intricate game mechanics.

Whether you are new to the field or looking to enrich your existing skill set, our courses provide a structured learning path that fits your schedule. You’ll engage with hands-on projects, tackle challenges, and earn certificates to showcase your achievements. And if you’re eager to dive into even more Godot content, browse our broad range of Godot courses. Continue learning, creating, and thriving with Zenva, where we help you go from beginner to professional in the exciting world of game development.


Embracing the power of the PopupMenu in Godot 4 unlocks a new level of interactivity for your games and applications. With the knowledge you’ve gathered, you’re well on your way to creating custom menus that are not only functional but also enhance the overall experience for your players or users. Remember, great UI is about more than looks; it’s about the seamless and intuitive connection between your game and its audience.

Don’t stop here—your journey into game development continues with every new feature and technique you master. Refine your skills, experiment with new ideas, and expand your knowledge by exploring our Godot Game Development Mini-Degree. We are excited to see the incredible games you’ll create and the innovative ways you’ll implement PopupMenus and other Godot 4 features. Step into your potential with Zenva, where every line of code brings you closer to becoming the game developer you aspire to be.

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.