BoxContainer in Godot – Complete Guide

Welcome to our comprehensive guide on the BoxContainer class in the powerful Godot 4 game development engine! If you’re looking to organize your user interface (UI) elements with ease and precision, mastering BoxContainer is essential. Whether it’s aligning buttons for a menu or structuring content for your game’s HUD, BoxContainers are your go-to tool. So strap in and get ready to learn how to tidy up your game interfaces like a pro!

What is BoxContainer?

BoxContainer is a versatile class in Godot’s UI system. It takes the hassle out of arranging controls either horizontally or vertically within your game’s UI. By understanding and utilizing this class, you can create responsive and well-organized layouts that adapt seamlessly to the changing needs of your dynamic game environments.

What is BoxContainer Used For?

BoxContainer is a cornerstone of UI design in Godot 4. It automatically arranges child controls according to the set orientation and ensures consistent spacing and alignment. This automatic arrangement feature helps in streamlining the UI creation process, saving time and reducing the manual tweaking often required in user interface management.

Why Should I Learn About BoxContainer?

Delving into the BoxContainer class can greatly improve the efficiency and aesthetics of your game’s UI. It’s crucial for:

  • Creating flexible layouts that adjust when the game window is resized or contents are dynamically changed.
  • Maintaining a clean codebase with reusable UI components.
  • Improving the overall user experience by ensuring clean and consistent alignments and spacing between different UI elements.

Learning how to leverage the BoxContainer class is invaluable, opening doors to creating professional and polished interfaces with minimal effort. Let’s dive into the world of Godot’s UI components and transform the way your game interacts with its players!

CTA Small Image

Setting Up Your First BoxContainer

To get started with using BoxContainer in Godot 4, let’s set up a simple vertical container that will layout several buttons one after the other. In the below example, we’ll create a `VBoxContainer` node which is specifically designed for vertical layout of child nodes:

var vbox =
vbox.align = BoxContainer.ALIGN_CENTER

var button1 =
button1.text = "Button 1"

var button2 =
button2.text = "Button 2"

var button3 =
button3.text = "Button 3"

This snippet creates a vertical box container (`VBoxContainer`) and adds three buttons to it. The `align` property is used here to center-align all the buttons within the container.

Adjusting Spacing and Alignment

Controlling the spacing between the elements in a BoxContainer is straightforward. You can set the `separation` property to define how many pixels should be between each control. You can also change the alignment of children within the container by using the `alignment` property.

// Set up our VBoxContainer from before
var vbox = ...
// Set custom separation
vbox.separation = 10

// Set the alignment of child controls to the end of the box
vbox.align = BoxContainer.ALIGN_END

The `separation` property set to `10` adds a 10-pixel gap between each button, and changing the `align` property to `ALIGN_END` aligns the buttons to the end (bottom) of the `VBoxContainer`.

Using HBoxContainer

Similarly, to create horizontal layouts you can use the `HBoxContainer`. Here’s how you can align a series of buttons horizontally:

var hbox =
hbox.align = BoxContainer.ALIGN_CENTER

var button1 =
button1.text = "Button 1"

var button2 =
button2.text = "Button 2"

var button3 =
button3.text = "Button 3"

In this example, `HBoxContainer` is used to line up buttons horizontally. We align the buttons to the center by setting the `align` property to `ALIGN_CENTER`.

Combining BoxContainers

For more complex UIs, you can combine multiple BoxContainers. Below we nest a `HBoxContainer` within a `VBoxContainer` to create a grid-like layout:

// Create a VBoxContainer and two HBoxContainers
var vbox =
var hbox1 =
var hbox2 =



// Add buttons to the first HBoxContainer
var button1 =
button1.text = "Button 1-1"

var button2 =
button2.text = "Button 1-2"

// Add buttons to the second HBoxContainer
var button3 =
button3.text = "Button 2-1"

var button4 =
button4.text = "Button 2-2"

This code snippet illustrates creating a two-by-two grid of buttons within your UI by combining `VBoxContainer` and `HBoxContainer`. By understanding and employing these basics, you can start crafting intricate and responsive layouts for your game’s UI.BoxContainers within Godot 4 are incredibly versatile, providing many properties and methods to control the behavior of your UI. Let’s explore more advanced functionality and show off the power of these containers with practical code examples.

Expanding the Size of Child Controls

Sometimes, you may want one of your UI elements to take up the maximum space possible within a BoxContainer. To achieve this, you can use the `size_flags_expand` property as demonstrated below:

// Create a VBoxContainer and add a button
var vbox =
var button =
button.text = "Expand Me"
// Tell the button to expand to fill the extra space
button.size_flags_vertical = Control.SIZE_EXPAND_FILL

Here, setting `size_flags_vertical` to `SIZE_EXPAND_FILL` tells the button to expand and fill the available vertical space within the `VBoxContainer`.

Aligning Controls Towards the Start or End

You can also align controls towards the top of a `VBoxContainer` or the left of an `HBoxContainer`, as shown here:

// VBoxContainer example
var vbox =
vbox.align = BoxContainer.ALIGN_START
// ... Add child controls

// HBoxContainer example
var hbox =
hbox.align = BoxContainer.ALIGN_START
// ... Add child controls

By setting the `align` property to `ALIGN_START`, controls will cling to the top or left edge of the container, depending on whether it’s a `VBoxContainer` or `HBoxContainer`.

Customizing the Appearance of Child Controls

It’s also possible to individually style child controls differently to make your UI pop. Here’s how you might go about customizing a button’s appearance:

// Create a button and customize its appearance
var button =
button.text = "Stylish Button"
button.rect_min_size = Vector2(100, 40)
// ... Set the button's theme or font

Here, we set `rect_min_size` to ensure the button has a minimum width and height, giving your control a customized look and feel.

Managing Visibility of UI Elements

Depending on your game’s context, you might want to show or hide certain UI elements without removing them from the BoxContainer:

// Assume you have a VBoxContainer with child buttons
var vbox = ... // your VBoxContainer
var button_to_toggle = ... // a specific button you want to show/hide

// Hide the button
button_to_toggle.visible = false

// Show the button
button_to_toggle.visible = true

To toggle visibility, simply set the `visible` property to `true` or `false`. This allows for dynamic UIs that react to game states without extensive restructuring of nodes.

Combining Containers for Advanced Layouts

For an advanced UI layout example, imagine you want a sidebar with buttons alongside a main content area. This could be the UI for an inventory screen or a complex menu system:

// Main VBoxContainer
var main_vbox =

// Sidebar as a VBoxContainer
var sidebar_vbox =
sidebar_vbox.size_flags_horizontal = Control.SIZE_EXPAND_FILL

// Main content area as an HBoxContainer
var content_hbox =
content_hbox.size_flags_expand = Control.SIZE_EXPAND_FILL

// Populate sidebar
for i in range(5):
    var button =
    button.text = "Option %d" % [i+1]

// Add Sidebar and content area to main VBox

// Then add this main box to the scene as needed

In this setup, we create a main vertical layout (`main_vbox`), add a sidebar (`sidebar_vbox`), and define a content area (`content_hbox`). Each sidebar button is created in a loop, and everything is neatly composed into the main container.

Through these examples, you should now have a solid grasp of the diversity of Godot’s BoxContainer class and how it can make creating complex and responsive UIs more manageable. With practice, you’ll be able to effortlessly design interfaces that not only look good but also provide a smooth user experience.Laying out dynamic content within your UI can be done by adjusting a control’s size flags and minimum size. This allows you to create interfaces that scale appropriately with different screen sizes or content changes. Consider the following examples:

Scaling Button Width in an HBoxContainer

// Add a button to an HBoxContainer that takes up all available width
var hbox =
var button =
button.text = "Full Width Button"
button.size_flags_horizontal = Control.SIZE_EXPAND_FILL

By setting the `size_flags_horizontal` property to `SIZE_EXPAND_FILL`, the button will expand to fill the available horizontal space within the `HBoxContainer`.

Limiting Minimum Button Size

// Set a minimum button size in a VBoxContainer
var vbox =
var button =
button.text = "Minimum Size Button"
button.rect_min_size = Vector2(150, 50)

The `rect_min_size` property ensures the button will never be smaller than 150 pixels wide and 50 pixels tall, regardless of the container size.

Horizontal and Vertical Alignment in BoxContainers
Sometimes, you’ll want your UI elements to align differently on the horizontal and vertical axes. Here’s how you can achieve that combination:

// Create a VBoxContainer with horizontally centered buttons
var vbox =

for i in range(3):
    var button =
    button.text = "Centered Button %d" % [i+1]
    button.align = Control.ALIGN_CENTER

Each button added to the `VBoxContainer` will be horizontally centered due to the `align` property being set to `ALIGN_CENTER`.

Stacking Containers
To create a complex UI layout, you might stack various types of containers. Consider a case with a `GridContainer` nested within an `HBoxContainer`:

// Create an HBoxContainer with a nested GridContainer
var hbox =

var grid =
grid.columns = 2

for i in range(4):
    var button =
    button.text = "Grid Button %d" % [i+1]

// Add additional components to HBoxContainer, such as another VBoxContainer
var additional_vbox =

// Now add this HBoxContainer to the scene

The `GridContainer` is responsible for organizing the buttons into a grid layout, and it is itself a child of the `HBoxContainer`, which can hold even more containers or controls as needed.

Responding to User Interaction
UI elements should react to user input. You can connect signals to BoxContainer children to respond to events, like button presses:

// Add a button and connect the 'pressed' signal
var button =
button.text = "Click Me"
button.connect("pressed", self, "_on_button_pressed")

func _on_button_pressed():
    print("Button was pressed!")

When the button is pressed, the `_on_button_pressed` function will be called, which, in this example, logs a message to the console.

Dynamic Content Adjustment
BoxContainers can also adapt to changes in their children’s visibility to reorganize the UI dynamically:

// Toggle visibility of a button, triggering the container to re-layout
var button =
button.text = "Toggle Visibility"

button.visible = !button.visible  // Toggle the button's visibility

Changing the `visible` property of a button to `false` will hide it and cause the `VBoxContainer` to adjust its layout accordingly, filling the space as if the button was not there.

These varied examples showcase the flexibility of BoxContainers in Godot 4 and serve as a solid foundation for your journey in UI design within Godot. With these tools, your interfaces will not only be more responsive but also more intuitive and engaging for your players.

Continuing Your Game Development Journey

Now that you’ve dipped your toes into the world of UI design with Godot’s BoxContainer class, it’s time to take your skills further. Embark on a journey to mastery with our comprehensive Godot Game Development Mini-Degree. Here, you can explore a wide range of topics from 2D and 3D game creation to advanced gameplay control flow, allowing you to build the exceptional games you’ve always imagined.

Our mini-degree is tailored not just for beginners, but also caters to more seasoned developers seeking to expand their portfolios. The Godot 4 engine is an excellent choice for cross-platform game development, known for its flexibility and ease of use. Enroll in our courses and gain hands-on experience with project-based lessons, interactive quizzes, and live coding sessions. By the end of your studies, you’ll have sharpened your skillset, created compelling games, and prepared yourself to grab the opportunities in the gaming industry.

Desire to see what else we offer? Browse through our broad selection of Godot courses for more in-depth tutorials and lessons on various aspects of game development. We at Zenva aim to equip you with practical knowledge and the confidence to create, innovate, and inspire with your projects. Your creative journey in game development awaits, and we’re here to support your growth every step of the way. Let’s build wonderful gaming experiences together!


The power to craft engaging game UIs is right at your fingertips with Godot’s BoxContainer class. We hope this tutorial has given you the tools to start building more effective and attractive user interfaces for your games. It’s just the start, though—a world of game development knowledge awaits you in our Godot Game Development Mini-Degree, where you’ll delve deeper into making your game ideas a reality.

Remember, learning is a journey, and every step you take with us at Zenva is one towards becoming the game developer you aspire to be. Don’t stop here; continue to expand your knowledge, refine your skills, and let your creativity run wild. Together, we will turn your passion for game development into tangible, playable art for the world to enjoy. Join us, and let’s transform your dreams into the next hit game!

Python Blog Image

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