VSplitContainer in Godot – Complete Guide

Welcome to a comprehensive dive into the VSplitContainer class in Godot 4, a pivotal element for UI development within your games and applications. As we journey through this tutorial, we will uncover the capabilities of this container, exploring its functionality and how it can enhance your Godot projects. Whether you’re new to Godot or an experienced developer looking to refine your UI design skills, this guide on using VSplitContainer will provide you with valuable insights and tools for designing dynamic and versatile user interfaces.

What Is VSplitContainer?

VSplitContainer is a special type of container in Godot’s UI system that allows developers to place two control nodes inside it and adjust their sizes vertically. It’s designed to offer flexibility and control, enabling a dynamic layout where the allocated space for each control can be easily adjusted by the user through an intuitive grabber handle.

What is VSplitContainer Used For?

The VSplitContainer shines in situations where you need a resizable interface, such as adjustable sidebars, panels, or any UI element that requires vertical separation. It improves the user experience by giving the user control over how much space each element on the screen takes up.

Why Should I Learn to Use VSplitContainer?

Mastering the VSplitContainer broadens your Godot UI toolkit, empowering you to create professional and sophisticated game interfaces. As user experience is a crucial aspect of game design, learning to implement these containers will enable you to craft not only visually pleasing but also highly functional interfaces that respond to your users’ needs.

CTA Small Image

Creating a Basic VSplitContainer

To start using a VSplitContainer, you first need to create one and add it to your scene. Below is an example of how to do this in GDScript:

var split_container = VSplitContainer.new()

Once you’ve added the VSplitContainer to your scene, you can start adding child nodes to it. The VSplitContainer will automatically divide its space among its children. Here’s how you can add child nodes:

var top_panel = Panel.new()
var bottom_panel = Panel.new()


Now you have a basic vertical split container with a top and bottom panel.

Configuring the Dragging Handle

In a VSplitContainer, the dragging handle that allows users to resize the panels can be adjusted in terms of its visibility and behavior. To make the handle invisible yet still functional, you can use the following code:

split_container.dragger_visibility = VSplitContainer.DRAGGER_HIDDEN_COLLAPSED

Alternatively, if you want the handle to be always visible regardless of the mouse cursor’s position:

split_container.dragger_visibility = VSplitContainer.DRAGGER_VISIBLE

Adjusting the Split Ratio

You can set the initial split ratio between the top and bottom panels using the `split_offset` property. This determines the offset of the splitting line from the top edge of the VSplitContainer.

# The offset value is in pixels
split_container.split_offset = 150

If you desire a ratio rather than a pixel offset, you’ll have to calculate it based on the VSplitContainer’s size. Below is an example to set the top area to take up 25% of the space:

func _ready():
    split_container.rect_min_size = Vector2(400, 400)  # Minimum size
    split_container.split_offset = int(split_container.rect_min_size.y * 0.25)

Controlling the Minimum Size of Panels

To ensure that each panel inside the VSplitContainer has a sensible minimum size, you can utilize the `rect_min_size` property on the child controls:

top_panel.rect_min_size = Vector2(100, 100)
bottom_panel.rect_min_size = Vector2(100, 100)

This ensures that neither the top nor the bottom panel can be resized smaller than 100 pixels in height, maintaining the usability and readability of the panels’ content.

Stay tuned for the next part of our tutorial, where we will delve into more advanced features and practical examples of using VSplitContainer to enhance your Godot UI. By mastering these essential features, you will be well-equipped to design robust and user-friendly interfaces for your games or applications.In the previous sections, we’ve covered the basics of creating a VSplitContainer and configuring its appearance and behavior. Now we’re going to dive into a few more advanced techniques and practical applications you can implement in your Godot projects.

Responding to User Resizes

Sometimes, you might want to trigger certain actions when the user resizes the panels. This can be accomplished by connecting the `resized` signal to a function in your code.

split_container.connect("resized", self, "_on_VSplitContainer_resized")

func _on_VSplitContainer_resized():
    print("The container was resized!")

With this functionality, you could update other parts of your UI or save the user’s preferred panel sizes.

Programmatic Resize

At times, you may want to resize the panels from within your code, such as setting a default size on game start or creating buttons that adjust the split container size for the user.

# Set the split offset to the middle
func _ready():
    split_container.split_offset = split_container.rect_min_size.y / 2

And here’s how you can make a button that maximizes the top panel:

func _on_MaximizeTopPanel_button_down():
    split_container.split_offset = split_container.rect_min_size.y - top_panel.rect_min_size.y

Alternatively, if you want a button to minimize the top panel to its smallest allowable size, you can write the following:

func _on_MinimizeTopPanel_button_down():
    split_container.split_offset = top_panel.rect_min_size.y

Saving and Loading Split Positions

To create an even more user-friendly experience, you may want to save the state of the split container when the game closes and load it when the game starts. You could use Godot’s `ConfigFile` class to save the split offset and then load and apply it during the `_ready()` function:

var config = ConfigFile()

func _exit_tree():
    config.set_value("UI", "split_offset", split_container.split_offset)

func _ready():
    var err = config.load("user://split_config.cfg")
    if err == OK:
        split_container.split_offset = config.get_value("UI", "split_offset")

Styling the SplitContainer

To make the VSplitContainer fit better into the visual style of your game, you can change its theme and style. Godot allows thorough styling via `Theme` resources, where you can set properties like the grabber’s icon or its color.

Assigning a new theme to the VSplitContainer:

var theme = Theme.new()
theme.set_stylebox("bg", "VSplitContainer", your_stylebox_resource)
split_container.theme = theme

These examples showcase the versatility of the VSplitContainer in Godot 4. By incorporating these methods, you can create dynamic, user-configurable UIs that elevate the quality of your game. Experiment with these features to discover how they can best serve your project’s needs, and remember that a well-designed UI is crucial for engaging gameplay experiences.Enhancing user control within your game interfaces is crucial for a polished and professional feel. Here we’ll look into some further intricacies of the VSplitContainer in Godot 4, providing additional code examples for practical use cases.

Let’s explore how to create collapsing panels, toggle the visibility of child nodes in response to resizing and even how to handle the VSplitContainer’s signals to create reactive UI elements.

Creating Collapsible Panels

Users often appreciate the ability to collapse panels to make more room for other UI elements. You can achieve this by setting the `collapsed` property of one of the panels to `true` or `false`.

Here’s an example of how to toggle the collapse state:

func _on_CollapseButton_pressed():
    var current_state = split_container.get_child(0).collapsed
    split_container.get_child(0).collapsed = !current_state

Responding to Collapsing Actions

With further interaction, you might want certain effects or actions to be triggered when a panel collides or expands. You can use the `panel_collapsed` signal for that:

split_container.get_child(0).connect("panel_collapsed", self, "_on_Panel_collapsed")

func _on_Panel_collapsed(collapsed):
    if collapsed:
        print("Panel has been collapsed")
        print("Panel has been expanded")

Visibility Toggling

Another useful feature is dynamically showing or hiding elements in response to how users interact with their available space. You could connect the `resized` signal to a function that checks the size and hides or shows elements accordingly:

split_container.connect("resized", self, "_on_VSplitContainer_resized")

func _on_VSplitContainer_resized():
    if split_container.rect_min_size.y - split_container.split_offset < 100:

Binding to Minimum Sizes

Ensuring content is always adequately displayed matters for usability and aesthetic. By binding minimal sizes to dynamic data or calculations, panels can behave responsively:

# Ensuring the bottom panel never goes below 20% of available space
func _ready():
    var min_size = split_container.rect_min_size.y * 0.2
    split_container.get_child(1).rect_min_size.y = min_size

Custom Dragger

Customizing the look and feel of the dragger can add that extra touch of uniqueness to your game’s UI:

var custom_stylebox = StyleBoxFlat.new()
custom_stylebox.bg_color = Color(0.25, 0.25, 0.25)
custom_stylebox.border_width_top = 2
split_container.add_stylebox_override("splitter", custom_stylebox)

Locking Panel Sizes

There may be cases when you want to lock the size of panels after a certain action or event. By setting the `dragger_visibility` property to `DRAGGER_HIDDEN_COLLAPSED`, you can make the panels unadjustable by the user.

# Locking the panels after a button press
func _on_LockPanelsButton_pressed():
    split_container.dragger_visibility = VSplitContainer.DRAGGER_HIDDEN_COLLAPSED

These code examples aim to demonstrate the flexibility and control that VSplitContainer provides when creating UI in Godot 4. With the capabilities to make dynamic adjustments, trigger actions based on user interaction and personalize the visual presentation, VSplitContainer is indeed an indispensable tool for UI development in your game. Experiment with these examples, tailor them to suit your project’s needs, and discover how empowering a well-tuned UI can be for the overall gameplay experience.

Continuing Your Game Development Journey in Godot

If you’ve enjoyed learning about the VSplitContainer class and are excited to take your Godot skills even further, our Godot Game Development Mini-Degree is the perfect next step. This comprehensive program is designed to take you from a beginner to a confident game developer by covering essential topics in 2D and 3D game creation. You’ll get hands-on experience building cross-platform games and strengthening your game design portfolio.

For those who want to explore a wider range of Godot topics, our collection of Godot courses offers an abundance of learning materials to suit your interests. Dive into various game genres, grasp advanced programming techniques, and learn game development at a pace that works for you. With the extensive library of high-quality content at Zenva, you have all the resources you need to transform your passion for games into practical, marketable skills.

We at Zenva believe that hands-on learning is key to understanding and mastering new concepts. Our content is built to help you stay engaged and motivated, making the learning process as enjoyable as it is informative. Embark on your next learning adventure with us, and experience the satisfaction of bringing your game ideas to life!


Through mastering the VSplitContainer and diving into the world of Godot 4, you’re now well-equipped to enhance your game’s UI with dynamic, user-friendly elements. The skills you’ve gained here are just the beginning of what you can achieve with Godot’s robust game development framework. We encourage you to keep experimenting, learning, and incorporating these techniques into your projects to create experiences that resonate with players.

Ready to turn your creativity up a notch? Whether you’re looking to fine-tune your Godot expertise or expand into new realms of game development, our Godot Game Development Mini-Degree is your gateway to professional-level game creation. Join us in this adventure, and let’s bring those innovative game concepts to fruition together!

Python Blog Image

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