OptionButton in Godot – Complete Guide

Welcome to our tutorial on the OptionButton class in Godot 4, a powerful and intuitive game engine that enables both beginners and experienced developers to bring their game ideas to life. Adding interactive and user-friendly elements to a game is essential for engaging players, and the OptionButton is a fundamental widget that can dramatically enhance your game’s user interface. By the end of this tutorial, you’ll understand what an OptionButton is, how it can be used in different contexts, and why mastering it can be a valuable addition to your development skillset.

What is an OptionButton?

An OptionButton in Godot 4 is a versatile UI element that, upon being pressed, displays a dropdown list of selectable options. This particular class inherits from Button, which in turn inherits from other classes that enable it to function within the Godot node system. What sets it apart is its capacity to hold multiple selectable choices and present the current selection as the button’s display text.

What is it for?

The primary use of an OptionButton is to provide players with a straightforward and compact way to make selections from a predefined list. This could be for settings like game difficulty, character selection, or any scenario where a choice needs to be made from multiple options.

Why Should I Learn It?

Understanding the OptionButton is crucial for game developers aiming to create a user-friendly interface. It is a fundamental component of the Godot UI system that aids in keeping your game’s menus organized and accessible. Learning to implement and manipulate an OptionButton will not only improve the aesthetic quality of your game but also ensure a seamless user experience, contributing to the overall polish and professionalism of your projects.

CTA Small Image

Creating an OptionButton

Let’s start by creating a simple OptionButton. In Godot, you can either create UI elements programmatically or by using the editor. Here’s how to create an OptionButton with GDScript:

var option_button = OptionButton.new()

func _ready():
    # Adding the OptionButton to the scene
    # Populating the OptionButton with items
    # Optional: Set the default selected option
    option_button.selected = 0

When you run this script, which should be attached to a Node in your scene, an OptionButton will appear with three options: “Easy”, “Medium”, and “Hard”.

Handling Selection Changes

Next, we’ll set up a signal to react to changes when an option is selected from the OptionButton. This enables you to perform an action based on the player’s selection.

func _ready():
    # Connecting the 'item_selected' signal to a callback function
    option_button.connect("item_selected", self, "_on_OptionButton_item_selected")

func _on_OptionButton_item_selected(id):
    print("Selected option: " + option_button.get_item_text(id))

The `_on_OptionButton_item_selected` function will print the text of the selected option to the console.

Styling the OptionButton

To style your OptionButton, you’ll need to access the Theme properties. You can set the font, icon, color, and others. Here’s how you might adjust the font size and color of the text:

func _ready():
    # Styling the Font of the OptionButton
    var new_font = DynamicFont.new()
    new_font.font_data = load("res://path_to_your_font.tres")
    new_font.size = 14
    option_button.add_font_override("font", new_font)
    # Changing the Color of the Font
    var font_color = Color(1, 1, 1) # white color
    option_button.add_color_override("font_color", font_color)

This will load a new font from a resource and apply it to the OptionButton, along with changing the font color to white.

Retrieving and Using Selected Values

Lastly, it’s important to understand how to get and use the values from the OptionButton. You might want to save the player’s selection for future reference, such as when changing game settings.

func _on_OptionButton_item_selected(id):
    var difficulty = option_button.get_item_text(id)
    print("You selected the difficulty: " + difficulty)
    # Now you can use the 'difficulty' variable to adjust game settings
    # Example: Setting the game difficulty level

func set_game_difficulty(difficulty):
    match difficulty:
            # Set easy difficulty settings
            # Set medium difficulty settings
            # Set hard difficulty settings

In this example, once an option is selected, the difficulty setting is applied immediately by calling a hypothetical `set_game_difficulty` function. Each match case would then contain the logic to adjust the game accordingly.

These examples cover the basics of creating, styling, and implementing functionality for an OptionButton in Godot 4. Stay tuned for the next part where we’ll cover more advanced concepts.In our continued exploration of the OptionButton in Godot 4, we’ll delve into more advanced features and customization options. Leveraging these capabilities can help you create more complex and intuitive UI elements that cater to your game’s needs.

Adding Icons to Options
To make your OptionButton more visually appealing, and perhaps more intuitive, you can add icons to each option. Here’s how:

func _ready():
    # Adding items with icons to the OptionButton
    option_button.add_icon_item(load("res://path_to_icon.png"), "Easy")
    option_button.add_icon_item(load("res://path_to_icon.png"), "Medium")
    option_button.add_icon_item(load("res://path_to_icon.png"), "Hard")

Icons alongside text can help players recognize options faster, especially in games where visuals play a significant role in the user interface.

Disabling and Enabling Options
There might be scenarios where you want some options to be unavailable. You can disable specific items in the OptionButton dropdown as follows:

func _ready():
    # Adding items as usual
    # Disable the "Hard" difficulty until the player unlocks it
    option_button.set_item_disabled(2, true)

Creating OptionButton Groups
In cases where you have multiple OptionButtons and you want to ensure that only one option across all buttons can be selected, you can create an OptionButton group. Here’s how you can do this:

var group = ButtonGroup.new()

func _ready():
    # First OptionButton
    var option_button1 = OptionButton.new()
    option_button1.add_item("Option 1")
    option_button1.group = group
    # Second OptionButton
    var option_button2 = OptionButton.new()
    option_button2.add_item("Option 2")
    option_button2.group = group
    # Now selecting an option in either will deselect the other

Customizing the Popup List
Sometimes you may want to customize the appearance of the dropdown list itself. The OptionButton allows you to get the PopupMenu node, which you can then modify. For example, you might change the background color of the list:

func _ready():
    var popup = option_button.get_popup()
    popup.add_color_override("panel_color_bg", Color(0.15, 0.15, 0.15))

Sorting and Clearing Options
You may want to sort the options alphabetically or clear all options and start anew. Godot provides methods for just that:

func _ready():
    # Adding items in a random order
    # Sorts items alphabetically
    # Clearing all options

Responding to a Mouse Over
To further enhance UI interaction, you can make your OptionButton respond when the mouse hovers over it. This might include changes in color, playing a sound, or displaying additional information.

func _ready():
    # Connecting the 'mouse_entered' and 'mouse_exited' signals
    option_button.connect("mouse_entered", self, "_on_OptionButton_mouse_enter")
    option_button.connect("mouse_exited", self, "_on_OptionButton_mouse_exit")

func _on_OptionButton_mouse_enter():
    option_button.add_color_override("font_color_hover", Color(0.8, 0.8, 0.8))
func _on_OptionButton_mouse_exit():
    option_button.add_color_override("font_color_hover", Color(1, 1, 1))

Localization and Internationalization
Lastly, considering localization and internationalization is paramount in game development. You can set up your OptionButtons to support multiple languages using Godot’s built-in localization tools.

func _ready():
    # Assuming 'Easy', 'Medium', and 'Hard' are keys in your localization file

Adding multiple languages can greatly increase your game’s accessibility and reach. By using the `tr()` function, Godot will automatically use the appropriate translation based on the current language setting.

These code examples showcase a few of the advanced capabilities of the OptionButton in Godot 4, allowing developers to create a rich and dynamic user interface. Dive into these features to build interfaces that not only look great but are also fully functional and accessible to a broader audience.To further enhance the functionality and interactivity of your OptionButtons, let’s explore additional capabilities such as querying information about the state of the dropdown list, responding to right-clicks, and customizing the behavior of each option.

Querying Information About Options
You can retrieve various pieces of information about the options in an OptionButton. For example, you may want to find the ID or text of the currently selected option:

func _ready():
    # To get the ID of the selected option
    var selected_id = option_button.get_selected_id()
    # To get the text of the selected option
    var selected_text = option_button.get_item_text(option_button.get_selected())

This functionality is particularly useful for debugging purposes or when you need to save the user’s selection to a file or database.

Responding to Right-Clicks
Sometimes you might want to provide additional functionality when a player right-clicks on an OptionButton. Here’s an example of how to handle right-click actions:

func _input(event):
    if event is InputEventMouseButton and event.button_index == BUTTON_RIGHT and event.pressed:
        if option_button.get_rect().has_point(to_local(event.position)):
            option_button.show_modal() # Show the dropdown list
            # Additional right-click handling goes here

This code block checks for a right-click input event and then determines whether the click occurred within the OptionButton’s rectangle area. If so, it will show the dropdown list and any other actions you wish to implement.

Customizing Individual Options
Customization can go further—let’s say you want to change the style of specific options. One way to achieve this is by using the `get_popup()` method to access individual items:

func _ready():
    # Customize the appearance of the second option
    var popup = option_button.get_popup()
    popup.set_item_custom_color(1, Color(1, 0, 0)) # Red color for the second item

Adding Separators Between Options
In certain situations, you may want to visually group related options by adding a separator. You can do this easily:

func _ready():
    option_button.add_item("First Option")
    option_button.add_item("Second Option")
    # Add a separator before the third option
    option_button.add_item("Third Option")

Separators create a clearer distinction between options and help users navigate the dropdown menu more effectively.

Controlling the Opening Direction
Depending on the OptionButton’s location on the screen, you may want the list to open upwards or downwards. Here is how you control the opening direction:

func _ready():
    # Assuming 'dir' can be either PopupMenu.POPUP_DIRECTION_DOWN or PopupMenu.POPUP_DIRECTION_UP
    option_button.get_popup().popup_direction = dir

By setting the `popup_direction` property, you ensure that your UI behaves consistently and remains fully visible, regardless of screen space constraints.

Reacting to the Dropdown Visibility
It can be useful to perform an action when the dropdown is shown or hidden. You might, for example, play a sound or change some visual aspect of the button:

func _ready():
    # Connecting the 'about_to_show' and 'popup_hide' signals
    option_button.get_popup().connect("about_to_show", self, "_on_OptionButton_dropdown_about_to_show")
    option_button.get_popup().connect("popup_hide", self, "_on_OptionButton_dropdown_hide")

func _on_OptionButton_dropdown_about_to_show():
    # Execute code right before the dropdown shows
func _on_OptionButton_dropdown_hide():
    # Execute code right after the dropdown hides

These functions could handle playing a sound effect and resetting any visual changes made when the dropdown was activated.

These examples illustrate the depth of customization and control you have over the OptionButton UI element in Godot 4, allowing for precise and tailored interactions that can elevate the player experience in your game. As you become more familiar with these functionalities, you’ll be able to better integrate the OptionButton into the visual and interactive design of your game’s UI.

Take Your Godot Skills to the Next Level

You’ve come a long way in mastering the OptionButton in Godot 4, learning not only its basics but also delving into advanced features and customization. This knowledge will undoubtedly enhance your game’s user interfaces and overall user experience. However, the world of game development with Godot is vast and there’s always more to learn!

For those of you eager to continue your game development journey, we highly recommend exploring our Godot Game Development Mini-Degree. This comprehensive collection of courses is designed to build upon what you already know and introduce you to new concepts and techniques in creating amazing games using Godot 4. You’ll gain hands-on experience across a wide range of game types and by the end, you’ll have a solid portfolio of projects to showcase your skills.

If you’re searching for a broader range of content, our diverse selection of Godot courses is perfect for expanding your knowledge. Whether you’re just starting out or looking to become a seasoned game developer, we have tailored courses to meet you right where you’re at. Continue your education with us, and propel your coding and game development abilities into the professional realm. With Zenva, you can transform your passion for games into a career.


Congratulations on completing this tutorial on the intricacies of the OptionButton in Godot 4! You now possess the knowledge to create dynamic and interactive menus that can truly captivate your players. Remember, every detail counts when it comes to crafting an immersive gaming experience, and the skills you’ve honed here are a testament to your dedication to game development excellence.

We hope this journey has sparked even greater enthusiasm for game creation within you. Continue to hone your abilities with our Godot Game Development Mini-Degree and become the game developer you’ve always aspired to be. At Zenva, we’re committed to empowering you with the knowledge you need to turn your game ideas into reality. Keep learning, keep creating, and let your creativity soar to new heights!

Python Blog Image

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