PanelContainer in Godot – Complete Guide

Welcome to an exciting journey into the world of game development with Godot 4! Today, we’re diving into the PanelContainer class—a versatile and essential component in creating polished and user-friendly game interfaces. Whether you’ve dabbled in Godot before or are taking your first steps in game development, understanding PanelContainer will help you add that extra flair to your games by neatly containing your UI elements within a stylized boundary. Stick around as we explore the fundamentals of PanelContainer, and learn why mastering this class can be a game changer for your projects!

What is PanelContainer?

PanelContainer is a class in Godot 4 that inherits from Container, which in turn is part of a hierarchy of classes designed to handle the user interface aspects of a game. This element is key when it comes to organizing your UI, as it neatly contains child controls within the confines of a StyleBox. Therefore, it serves as a dedicated space to hold other interface elements together, giving them a consistent, defined outline and style.

What is PanelContainer Used For?

The main use of a PanelContainer is to group UI elements such as buttons, labels, or sprites, and provide them with a unified visual boundary. It’s often used to create menus, HUDs (Heads-Up Displays), and other interface panels. By setting up a StyleBox, developers can define the background style for the PanelContainer, enabling it to blend seamlessly with the game’s aesthetic.

Why Should I Learn About PanelContainer?

Delving into PanelContainer is vital for a few reasons:

– **Enhanced UI Design**: Understanding how to use PanelContainer helps in crafting more organized and visually appealing user interfaces.
– **Customization and Styling**: It allows for extensive customization of your game’s UI, promoting a unique and consistent design that aligns with your game’s theme.
– **Efficiency**: Managing UI layout becomes much more manageable with containers, potentially saving time and resources during the development process.

Ready to discover how PanelContainer can elevate your game’s UI? Let’s get started with coding examples and practical applications that will bring your interface design to the next level!

CTA Small Image

Creating a Basic PanelContainer

Before we jump into the code, ensure that Godot Engine is installed and ready. Once you’ve set up a new project, follow along to create your first PanelContainer.

Step 1: Adding a PanelContainer Node

var panel =

Here, we create a new PanelContainer instance and add it to the current scene, which can be the main scene or any user interface related scene.

Step 2: Customizing Your Panel Background

Next, let’s customize the look of our PanelContainer using a StyleBox. In Godot 4, StyleBoxFlat is a great choice to start off.

var style =
style.bg_color = Color(0.15, 0.15, 0.15)
style.border_color = Color(1, 1, 1)
style.border_width_all = 2

panel.add_stylebox_override("panel", style)

In this snippet, we’re creating a flat, styled box with a dark background, a light border, and a border width of 2 pixels. Using `add_stylebox_override`, we’re applying this style to our PanelContainer.

Organizing UI Elements With PanelContainer

Let’s dive deeper and add some UI elements to our PanelContainer, like Buttons and Labels, and observe how they are organized.

Step 1: Adding Buttons to a PanelContainer

var button1 =
button1.text = "Button 1"

var button2 =
button2.text = "Button 2"

This sets up two buttons within our PanelContainer. As you can see, it’s a matter of simply creating the items and adding them as children to the PanelContainer node.

Step 2: Adding a Label to PanelContainer

var label =
label.text = "Welcome to Zenva!"

Similar to buttons, adding a label is straightforward. This can help you provide instructions or context within your UI panel.

Positioning and Alignment Inside PanelContainer

In Godot, positioning and aligning elements within a container is crucial for a polished UI. Let’s manipulate the way our buttons and label interact with the PanelContainer.

Step 1: Centering Elements

button1.align = Button.ALIGN_CENTER
button2.align = Button.ALIGN_CENTER
label.align = Label.ALIGN_CENTER

This will align the text of our buttons and label to the center, offering a tidy, centered appearance within the PanelContainer.

Step 2: Positioning Elements

While containers handle positioning automatically, we can still control the margin and spacing around our UI elements to create a structured layout.

panel.custom_constants_margin_top = 10
panel.custom_constants_margin_bottom = 10
panel.custom_constants_separation = 5

These lines adjust the top and bottom margins as well as the separation between elements. Play with these values to affect how your UI elements are spaced within the PanelContainer.

Stay tuned as we proceed with our next tutorial pieces where we will delve into advanced configurations and interactions! Remember, with the solid basics you’ve learned here, you’re well equipped to start experimenting and creating intricate UI designs with PanelContainer in Godot 4.Let’s build upon our PanelContainer by integrating signals and making our UI interactive. Godot’s signal system is powerful for creating responsive interfaces, so we’re going to connect our buttons to perform specific actions when pressed.

Connecting Buttons to Signals

button1.connect("pressed", self, "_on_button1_pressed")
button2.connect("pressed", self, "_on_button2_pressed")

With these lines, each button is connected to a method that will be called when the button is pressed. Now, let’s define the methods that handle these signals.

func _on_button1_pressed():
    print("Button 1 was pressed!")

func _on_button2_pressed():
    print("Button 2 was pressed!")

If you run the game at this point and press the buttons, you should see the corresponding print statements in the output.

Dynamic Content Management with PanelContainer

A PanelContainer can also dynamically manage content, such as adding and removing child nodes at runtime.

Removing an Element

To remove a UI element from the PanelContainer, you can use the `remove_child()` method.


Adding Elements at Runtime

Conversely, you can also add elements at runtime, which is useful for updating the UI based on game events.

var new_button =
new_button.text = "New Button"

Using Themes with PanelContainer

To further customize the look of your PanelContainer, you can use themes. A theme can be applied to a node and all its children, providing consistent styling across multiple UI elements.

Creating a Theme

var theme =
var default_font =

default_font.font_data = load("res://path_to_your_font.tres")


Here, we create a new theme and set a custom font as the default font. Then, we apply the theme to our PanelContainer.

Applying a StyleBox to the Theme

Let’s also add a style for our buttons within the theme.

var button_style =
button_style.bg_color = Color(0.2, 0.5, 0.8)
button_style.border_width_all = 1

theme.set_stylebox("normal", "Button", button_style)

button1.add_theme_override("normal", button_style)
button2.add_theme_override("normal", button_style)

This applies a custom StyleBox to the ‘normal’ state of Buttons. The same style can be reused for other buttons by referencing the theme.

Enhancing Layouts with Size Flags

In Godot, Size Flags can influence how space is allocated within Containers. Let’s apply some to our buttons for a better layout.

Expanding Buttons

button1.size_flags_horizontal = Control.SIZE_EXPAND_FILL
button2.size_flags_horizontal = Control.SIZE_EXPAND_FILL

By setting the `SIZE_EXPAND_FILL` flag, we’re telling Godot to let the buttons expand to fill the available horizontal space within the PanelContainer.

Fixing Aspect Ratios

Sometimes, you might want certain UI elements to maintain their aspect ratio.

label.rect_min_size = Vector2(100, 40)
label.size_flags_stretch_ratio = 2

Here, we set a minimum size for the label and use the `size_flags_stretch_ratio` to maintain a 2:1 width to height ratio while resizing.

With these additions, our PanelContainer has become much more than a static UI box. It can now appropriately respond to input, dynamically alter its content, and apply coherent theming across all its children. Through these tools, you’re well-prepared to build intuitive and visually consistent interfaces, an essential skill set for creating professional-level games with Godot 4. Keep practicing, and soon you’ll find that the UI possibilities are limitless in Godot!As we continue exploring the potential of PanelContainer in Godot 4, it’s important to delve into some more advanced features and coding examples that will help you refine your UI even further. We’ll look at various scenarios and how we can enhance our PanelContainer’s functionality and aesthetics.

Adjusting Panel Margins

Often, you may want to define the space around the entire PanelContainer itself, rather than just the internal elements. Here’s how you can adjust the PanelContainer margins:

panel.margin_left = 10
panel.margin_top = 20
panel.margin_right = 10
panel.margin_bottom = 20

This will add a margin around the PanelContainer, separating it from other elements or the edge of the screen.

Implementing Hover Styles for Buttons

Adding hover styles to your buttons can significantly improve the user experience. Here’s how you might define a hover style within a theme and apply it to a button:

var button_hover_style =
button_hover_style.bg_color = Color(0.25, 0.55, 0.85)

theme.set_stylebox("hover", "Button", button_hover_style)

button1.add_theme_override("hover", button_hover_style)
button2.add_theme_override("hover", button_hover_style)

When you hover over the buttons, you should now see the background color change, indicating interactivity.

Organizing Child Nodes with VBoxContainer and HBoxContainer

To better organize the UI elements within a PanelContainer, you can use VBoxContainer and HBoxContainer nodes for vertical and horizontal alignment.

var vbox =


This snippet will arrange your label and buttons vertically. If you want horizontal alignment instead, replace `VBoxContainer` with `HBoxContainer`.

Adjusting Container Alignment and Separation

Containers have properties to adjust the alignment and separation of their child nodes:

vbox.alignment = BoxContainer.ALIGN_CENTER
vbox.custom_constants_separation = 10

This centers the elements within the VBoxContainer and ensures there’s a separation of 10 pixels between them.

Using Containers with Size Flags

To take further control over layout management, combine containers with size flags:

button1.size_flags_vertical = Control.SIZE_EXPAND_FILL
button2.size_flags_vertical = Control.SIZE_EXPAND_FILL

This example makes the buttons expand and fill up the vertical space within the VBoxContainer evenly.

Responsive UI with Anchors and Margins

Finally, to create a UI that adapts to different screen sizes, use anchors and margins to position your PanelContainer. This ensures that regardless of the resolution, your UI elements maintain their intended layout.

panel.rect_min_size = Vector2(300, 200)
panel.anchor_left = 0.5
panel.anchor_top = 0.5
panel.margin_left = -150   # Half of the rect_min_size.x
panel.margin_top = -100    # Half of the rect_min_size.y

With this setup, the PanelContainer is centered on the screen, and its size is maintained across resolutions.

Through these more advanced examples, we can see how Godot 4’s UI system, particularly the use of PanelContainers, offers a robust and versatile toolkit for creating dynamic and responsive user interfaces for your games. It empowers you to not only create visually engaging elements but also ensures they perform seamlessly across different devices. Practicing with these concepts will no doubt enhance the quality of your game development projects. Keep experimenting with Godot’s diverse features, and watch your game interfaces come to life with both functionality and style!

Continue Your Game Development Journey with Zenva

Diving into the world of Godot and mastering elements like the PanelContainer is just the beginning. To expand your skills and explore the full spectrum of game development with this powerful engine, we invite you to check out our Godot Game Development Mini-Degree. This comprehensive program covers a range of topics, from 2D and 3D games to complex gameplay mechanics, ensuring you have the knowledge and hands-on experience to bring your creative visions to life.

Whether you are a beginner looking to get a solid start in game development or someone who has already grasped the basics and wants to enhance your capabilities further, our Mini-Degree offers a flexible learning path that fits your pace. Plus, the Godot Engine is open-source and free, with a vibrant community to support your learning journey.

For a broader array of game development opportunities, don’t forget to explore our full collection of Godot courses—each designed to empower you with the skills to create, innovate, and perhaps even kickstart your own ventures in the gaming industry. Keep on coding, and let Zenva be your guide to turning your game development dreams into reality!


Embarking on the path to game development with tools like Godot 4 can be both exhilarating and challenging. By exploring and understanding versatile components like the PanelContainer, you are setting a strong foundation for creating intuitive and visually captivating user interfaces. Remember, the elements you learn today are the building blocks for the complex and engaging games you’ll create tomorrow. We at Zenva are excited to accompany you on this creative journey, providing you with the knowledge and resources you need at every step.

Whether you’re polishing your first game or embarking on a larger project, our Godot Game Development Mini-Degree is the ultimate resource to hone your skills. With disciplined practice and our expertly crafted curriculum, you’ll be turning your game development aspirations into a playable reality in no time. So, keep experimenting, keep learning, and let your game development adventure with Zenva elevate you to new heights!

Python Blog Image

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