Popup in Godot – Complete Guide

Welcome to our tutorial on the Popup class in Godot 4, a powerful and versatile tool for game developers looking to add engaging UI elements to their games. Popups can provide information, gather input, or simply serve as a pause menu in your game, and Godot makes implementing them intuitive and straightforward. By the end of this tutorial, you’ll have a solid grasp on how to use the Popup class to enhance the user experience in your games. Whether you’re a beginner seeking to level up your UI game or an experienced coder refining your skills, this guide will provide useful insights into making the most of Godot’s Popup class.

What is the Popup Class?

The Popup class in Godot 4 is a fundamental component when creating contextual windows or panels in your game. It inherits from the Window class and provides a modal window which can be customized for various purposes within your project.

What Can the Popup Class Be Used For?

Popup windows are extremely versatile within a game development context, featuring use-cases like displaying game instructions, creating inventory screens, showcasing achievement notifications, or implementing custom dialogues between characters.

Why Should I Learn About the Popup Class?

Mastering the Popup class equips you with the ability to create responsive and interactive UI elements that elevate the gaming experience. They are critical for player feedback, in-game communication, and providing a professional and polished look to your Godot projects. Learning about Popups is essential for any game developer focusing on players’ engagement and satisfaction.

CTA Small Image

Creating a Simple Popup

To begin, let’s create a basic Popup. First, you’ll need to add a Popup node to your scene:

var my_popup = Popup.new()

To display this Popup, you can either set it to appear when a certain event occurs or just show it for demonstration:


Remember, the Popup method `popup_centered()` centers the popup on the screen.

Customizing Popup Appearance

You’ll likely want to customize your Popup. You can set the window title and size like this:

my_popup.window_title = "My Custom Popup"
my_popup.rect_min_size = Vector2(300, 200)

Godot 4 provides flexibility in design, so you can set the Popup’s theme or add custom styles for a tailored appearance.

Adding Content to Popups

Popups aren’t much without content. You can add any control node as a child to customize your Popup. Here’s how you would add a Label to your Popup:

var label = Label.new()
label.text = "Hello, this is a popup!"

And to make your Popup interactive, you can add a Button that closes the Popup when pressed:

var button = Button.new()
button.text = "Close"
button.connect("pressed", my_popup, "hide")
button.rect_min_size = Vector2(100, 50)

Place the button at the bottom of the Popup:

button.anchor_top = 1.0
button.anchor_bottom = 1.0
button.margin_top = -button.rect_min_size.y - 10
button.margin_bottom = -10

Responding to Popup Events

It’s important to handle Popup events to control the flow of your game. For instance, you might want a function to run when the Popup is closed. Connect the Popup’s `about_to_show` or `popup_hide` signals to callback methods:

my_popup.connect("about_to_show", self, "_on_MyPopup_about_to_show")
my_popup.connect("popup_hide", self, "_on_MyPopup_hide")

func _on_MyPopup_about_to_show():
    print("Popup is about to show!")

func _on_MyPopup_hide():
    print("Popup was hidden!")

This example demonstrates how to execute code right before a Popup shows and after it hides, allowing you to take action at these critical moments.

Creating Timed or Auto-Hide Popups

Sometimes, popups should only stay on the screen for a predetermined amount of time or disappear when a player clicks outside of them. Here’s how to set an auto-hide timeout:

my_popup.popup_centered_msec(2000) # Popup shows for 2 seconds

To allow the Popup to hide when clicked outside, set `hide_on_check_unhandled_input`:

my_popup.hide_on_check_unhandled_input = true

These examples lay the groundwork for creating and customizing basic Popups in Godot. Now, let’s move on to more advanced features and scenarios where Popups enhance gameplay and interaction.Popups can also be equipped with various interactive elements, such as text inputs and dropdown menus, to gather information from the player or provide them with choices.

Let’s add a `LineEdit` control to our Popup, allowing players to input text:

var line_edit = LineEdit.new()
line_edit.rect_min_size = Vector2(250, 30)
line_edit.margin_top = 50
line_edit.margin_left = 25

Next, if we want the player to make a selection from a list, we would use an `OptionButton`:

var option_button = OptionButton.new()
option_button.rect_min_size = Vector2(250, 30)
option_button.margin_top = 100
option_button.margin_left = 25

option_button.add_item("Option 1", 0)
option_button.add_item("Option 2", 1)
option_button.add_item("Option 3", 2)

Handling interaction with these elements is straightforward using signals. Let’s say you want to trigger an action when the text in the `LineEdit` changes:

line_edit.connect("text_changed", self, "_on_LineEdit_text_changed")

func _on_LineEdit_text_changed(new_text):
    print("New text input: ", new_text)

In the case of `OptionButton`, you’d likely want to react to the player’s choice:

option_button.connect("item_selected", self, "_on_OptionButton_item_selected")

func _on_OptionButton_item_selected(id):
    print("Selected option ID: ", id)

Positioning each element within your Popup is key to a clean layout. You can use the `Anchor` and `Margin` properties to neatly align your components. For example, center an `OptionButton` like this:

option_button.anchor_left = 0.5
option_button.anchor_right = 0.5
option_button.margin_left = -125 # Half the rect_min_size.x
option_button.margin_right = 125 # Half the rect_min_size.x

Finally, let’s go over binding data or methods to your Popup elements. If your Popup performs a specific function, like confirming an action, you can bind a method to `Button`:

var confirm_button = Button.new()
confirm_button.text = "Confirm"
confirm_button.rect_min_size = Vector2(100, 50)

# Bind the method with an argument. If you had a method to delete an item, you could pass the item ID
confirm_button.connect("pressed", self, "_on_ConfirmButton_pressed", [some_item_id])

confirm_button.anchor_top = 1.0
confirm_button.anchor_bottom = 1.0
confirm_button.margin_top = -confirm_button.rect_min_size.y - 10
confirm_button.margin_bottom = -10

func _on_ConfirmButton_pressed(item_id):
    print("Confirmed action for item: ", item_id)
    delete_item(item_id) # Hypothetical method to delete an item

By combining these elements and techniques, you begin to harness the full potential of the Popup class. These components not only make your UI more interactive but also open the doors to a multitude of gameplay mechanics, all with a clean and professional presentation that keeps players engaged and your game’s design soaring.Adding a bit more dynamic behavior to your Popups can significantly enrich the player’s experience. In many cases, you want the Popup to behave according to game logic, such as adapting its content dynamically or positioning it in response to player interactions.

Dynamic Content Adjustments

For instance, if you want to update the Popup’s label text depending on certain conditions in the game, you could have:

var game_condition = "win"

if game_condition == "win":
    label.text = "You won!"
elif game_condition == "lose":
    label.text = "You lost."

A more complex example may involve updating a score display within the Popup each time the score changes:

var score_label = Label.new()
score_label.text = "Score: 0"

func update_score(new_score):
    score_label.text = "Score: " + str(new_score)

Draggable Popups

Sometimes, you may want to allow the player to move the Popup around. To achieve this, we have to set `mode` in the `PopupPanel` or create a script on the Popup node to handle drag behavior:

var dragging = false
var drag_offset = Vector2()

func _input(event):
    if event is InputEventMouseButton and event.button_index == BUTTON_LEFT:
        if rect_global_position.distance_to(event.position) < rect_size.length():
            drag_offset = rect_global_position - event.position
            dragging = event.pressed
    elif event is InputEventMouseMotion and dragging:
        rect_global_position = event.position + drag_offset

When the player clicks and holds the left mouse button within the Popup’s boundaries, they can drag it around the screen until they release the button.

Animating Popups

Adding animation can make your Popups appear more dynamic. You can use `Tween` to animate their properties. Here is an example that makes the Popup fade in:

var tween = Tween.new()
tween.interpolate_property(my_popup, "modulate", Color(1, 1, 1, 0), Color(1, 1, 1, 1), 1, Tween.TRANS_LINEAR, Tween.EASE_IN_OUT)

This will interpolate the `modulate` property of the Popup from fully transparent to fully opaque, creating a fade-in effect over one second.

Dynamic Positioning

A Popup might open in relation to a certain in-game event or object. For instance, a Popup that appears above a character’s head when they are interacted with could be positioned like this:

func show_popup_at_position(position):
    my_popup.rect_global_position = position - Vector2(my_popup.rect_size.x/2, my_popup.rect_size.y + 10)

In the above example, `position` would likely be the global position of the character, and the Popup is set just above their head.

Responsive Design for Popups

Given a wide range of possible resolutions that players might use, it’s crucial for Popups to be responsive. Godot’s Anchor and Margin system works well for responsively positioning UI elements:

my_popup.anchor_right = 0.5
my_popup.anchor_bottom = 0.5
my_popup.margin_left = -my_popup.rect_min_size.x/2
my_popup.margin_top = -my_popup.rect_min_size.y/2

By setting the anchors to 0.5 and the margins to negative half of the Popup’s size, you ensure the Popup remains centered regardless of screen resolution.

By tapping into these advanced features, your Popups become not just informative UI elements but interactive tools that contribute to an immersive game environment. The responsiveness and dynamism of your UI can significantly boost the overall quality of your game, making it adaptable and enjoyable for a broad audience. With Godot’s powerful scripting capabilities, the possibilities are limited only by your imagination.

Where to Go Next in Your Game Development Journey

Congratulations on taking the first steps towards mastering Popup class functionality in Godot 4! While this tutorial has hopefully provided you with a strong foundation, the world of game development in Godot is vast and constantly evolving. To continue expanding your skills and diving deeper into the endless possibilities, the Godot Game Development Mini-Degree at Zenva Academy is an excellent next step.

Our Mini-Degree is specifically designed to guide you through the intricacies of the Godot 4 engine, from the very basics to the creation of more complex games in genres like platformers, RPGs, and survival games. You’ll be working on hands-on projects that will not only solidify your understanding but also contribute to a professional portfolio that showcases your abilities.

If you’re looking to broaden your horizons even further, be sure to explore our full range of Godot courses. With our extensive library, Zenva provides a learning path for every game development enthusiast, whether you are just starting out or looking to fine-tune your expertise. Each of our courses is crafted to empower you with the skills needed to turn your passion for games into a career or to simply create the projects you’ve always dreamed of. Start your next learning adventure with us, and keep coding your way to success!


Diving into the world of game development with Godot 4 and its Popup class can transform your projects with interactive, responsive UIs that captivate players. Remember, a well-designed interface is not just a tool for communication—it’s an essential part of the gaming experience itself. The skills you’ve gained here are just the beginning of what you can achieve with Godot.

To continue your journey and unlock your full potential as a game developer, consider joining us at Zenva Academy and enrolling in our Godot Game Development Mini-Degree. Allow us to guide you further with comprehensive lessons, detailed tutorials, and real-world projects that build your confidence and your portfolio. Take the leap today, and make the games you’ve always wanted to—your future in game development awaits!

Python Blog Image

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