SplitContainer in Godot – Complete Guide

When diving into the world of game development with Godot 4, understanding the user interface (UI) components is crucial for crafting an interactive and intuitive game experience. Among these is the SplitContainer class – a versatile container for creating adjustable layouts in your games or applications. This tutorial will unveil the mysteries of the SplitContainer, guiding you through its features and demonstrating how you can leverage it to enhance your Godot projects. Whether you’re crafting an elaborate level editor or a simple menu, mastering the SplitContainer can elevate your UI design skills.

What is SplitContainer?

The SplitContainer is a UI component in Godot 4 that allows you to divide your screen into two sections with a draggable divider. This component is especially useful when you want to create resizable panels or areas inside your game or tool. It offers a flexible way to manage space within your UI and is conducive to a customizable user experience.

What is it for?

SplitContainer serves a variety of purposes:

  • Creating adjustable layouts where the user can dynamically resize UI components.
  • Enhancing level editors, debug menus, or any tool that benefits from adjustable space distribution.
  • Improving user interaction by allowing them to customize their workspace to their preference.

Why Should I Learn It?

Learning how to use the SplitContainer can have a significant impact on the quality of your game or application’s UI.

  • It grants you the power to design responsive and adaptable interfaces that cater to the needs of your users.
  • It provides an essential skill set for creating professional-grade UIs within the Godot Engine, a staple for any aspiring game developer.
  • With UI being a crucial aspect of player interaction, a solid grasp of UI elements like the SplitContainer can make the difference between an average experience and a great one.

Ready to unlock the potential of SplitContainer? Let’s move on to the coding examples to see it in action!

CTA Small Image

Basic Setup of SplitContainer

To get started, let’s create a basic SplitContainer from scratch and add it to our scene.

var split_container = SplitContainer.new()

This code creates a new SplitContainer and adds it to the current scene. Now, let’s populate it with two panels.

var panel1 = Panel.new()
var panel2 = Panel.new()


Panel1 and Panel2 are the children of our SplitContainer. You can now run your scene to see the default behavior of the SplitContainer with two equally divided areas.

Adjusting the SplitContainer

One of the most important aspects of using a SplitContainer is the ability to customize the initial split ratio and configure the drag behavior. Here’s how you can set the initial split position and the minimum size of each panel:

# Set the split position, where the value is the offset from the start of the SplitContainer
split_container.split_offset = 100

# Set the minimum size allowed for the first and second child
split_container.set_child_min_size(0, 50) # First child min size
split_container.set_child_min_size(1, 50) # Second child min size

After setting the initial split position and minimum sizes, your UI will adhere to these parameters when resized.

Controlling the Draggable Area

Depending on your needs, you might want to limit or expand the draggable area. You can control whether the splitter is draggable and set its collapse mode. Here’s how:

# Make the splitter undraggable
split_container.draggable = false

# Allow the splitter to collapse the first child (Panel1)
split_container.collapse_mode = SplitContainer.COLLAPSE_MODE_BEGIN

Disabling the draggable property fixes the position of the divider, and setting the collapse mode allows one of the panels to be collapsible, a feature that can be very handy for maximizing work areas.

Styling Your SplitContainer

Styling is essential to ensure that the SplitContainer matches the aesthetic of your game or application. With Godot’s theme system, you can customize the appearance. Here’s an example of changing the style of our SplitContainer:

# Create a new style for the panels
var style = StyleBoxFlat.new()
style.bg_color = Color(0.12, 0.14, 0.15)
style.border_color = Color(0.33, 0.35, 0.36)
style.border_width_top = style.border_width_bottom = 1
style.border_width_left = style.border_width_right = 1

# Apply the style to the entire SplitContainer
split_container.add_stylebox_override("panel", style)

This snippet creates a new StyleBoxFlat, sets its properties, and applies it as an override for the SplitContainer’s panels. You can customize this style further to fit your design requirements.

With these basics under your belt, the SplitContainer should no longer be a mystery. It’s a capable UI component ready to be molded into whatever your project needs. As we continue, we’ll explore more advanced use cases and practical examples, so stay tuned for the next part of our tutorial!

Moving forward in our exploration of the SplitContainer, let’s delve into more advanced functionalities and their corresponding code examples. We’ll touch on signal connections, runtime manipulations, and more styling tips to ensure that you can fully customize the SplitContainer to your needs.

One of SplitContainer’s useful features is emitting signals when the splitting divider is moved. This allows you to perform actions or update other parts of your UI in response. Here’s how you would connect a signal to your splitter:

# Connecting the 'dragged' signal to a local method
split_container.connect("dragged", self, "_on_SplitContainer_dragged")

func _on_SplitContainer_dragged(offset):
    print("The SplitContainer is now at: ", offset)

When the SplitContainer is dragged, the ‘_on_SplitContainer_dragged’ function will be called, and the current offset value will be printed to the console. This can be very useful for debugging or for updating other parts of your UI in real-time.

You might encounter scenarios where you need to control the SplitContainer’s split offset based on runtime conditions, not just on user interactions. To change the position of the splitter programmatically, you can adjust the ‘split_offset’ property:

# Dynamically set the split offset during runtime
split_container.split_offset = 200

This line sets the split offset to 200 pixels from the starting edge of the SplitContainer, which can be used, for example, to restore a saved user preference when your game or application starts.

Now, suppose you’d like to control whether the splitter can be moved beyond its initial setting at runtime. You can toggle the ‘draggable’ property:

# Toggle the ability to drag the splitter
split_container.draggable = !split_container.draggable

If the splitter was draggable, it will now be fixed, and vice versa. This functionality is important when you want to prevent the user from modifying the UI during certain operations, like during a loading process.

Godot also allows for more elaborate styling options using themes. If you want to change the color of the splitter itself, this is done by overriding the ‘grabber’ stylebox:

# Create a new style for the grabber
var grabber_style = StyleBoxFlat.new()
grabber_style.bg_color = Color(0.40, 0.44, 0.47)

# Apply the style to the split’s grabber area
split_container.add_stylebox_override("grabber", grabber_style)

This snippet creates a new style specifically for the grabber and applies it to the SplitContainer. The grabber is the draggable area of the SplitContainer, and customizing it can help integrate the component more closely with your project’s UI.

Animation can also be introduced to the SplitContainer for a more dynamic UI. For instance, you can animate the offset to smoothly transition to a new position:

# Animate the split offset to a desired position over time
split_container.animate_property("split_offset", split_container.split_offset, 400, 0.5, Tween.TRANS_LINEAR, Tween.EASE_IN_OUT)

This will animate the ‘split_offset’ property from its current value to 400 over 0.5 seconds with linear transition and ease-in-out easing. Such effects can be used to enhance user feedback or as part of your UI’s dynamic behaviors.

By incorporating these advanced functionalities of SplitContainer into your Godot projects, you can craft a UI that is not only responsive and user-friendly but also coherent with your game’s theme and behavior expectations. Armed with these tools, the power of UI customization in Godot 4 is truly at your fingertips.

Expanding upon the possibilities of SplitContainer, let’s look into how we can interact with the children of the container to further control the user interface. Each side of the SplitContainer can be dynamically managed to respond to the needs of the application or game.

For example, you may want to adjust the contents of the panels based on the size allotted to them by the SplitContainer. This can include resizing text, scaling images, or rearranging controls. Here’s how you could update the content size of a child Control node:

func _on_SplitContainer_dragged(offset):
    var size = split_container.get_child(0).rect_min_size
    size.x = offset
    split_container.get_child(0).rect_min_size = size

    # Do the same for the second child, if necessary
    # ...

With this function, whenever the SplitContainer is dragged, the minimum size of the first child is adjusted to match the new offset. It ensures that the content within the panel scales correctly without overflowing or underflowing.

You can also listen to size changes of the SplitContainer itself to reorganize or resize children proportionally:

# Assuming we have set up a notification for size changes earlier
func _notification(what):

func _resize_children():
    var available_space = split_container.rect_size.x - split_container.split_offset
    split_container.get_child(1).rect_min_size.x = available_space

This code ensures that the second child panel resizes dynamically as the SplitContainer’s size changes, maintaining a consistent layout regardless of window resizes or other UI changes.

Another aspect to consider when working with UI elements like the SplitContainer is the convenience of user settings. Storing the last position of the splitter can help personalize the gaming experience. This can be done using Godot’s built-in ConfigFile:

# Save the current split offset position
var config = ConfigFile()
config.set_value("Settings", "split_offset", split_container.split_offset)

# Load and set the split offset position when the app starts
split_container.split_offset = config.get_value("Settings", "split_offset", 100)  # Default to 100 if not found

These snippets write the current offset of the SplitContainer to a configuration file upon a certain event (like closing the application), and read it back when the application starts, setting the SplitContainer to its previous state.

Furthermore, integration with animations can not only enhance visual appeal but also provide a better user experience. If you’re creating a more complex UI where side panels are expanded or hidden based on user input, you can animate these changes through the SplitContainer:

# Function to hide the left panel smoothly
func hide_left_panel():
    var tween = Tween.new()
    tween.interpolate_property(split_container, "split_offset", split_container.split_offset, -split_container.get_child(0).rect_min_size.x, 0.4, Tween.TRANS_QUAD, Tween.EASE_OUT)

# Function to show the left panel smoothly
func show_left_panel():
    var tween = Tween.new()
    tween.interpolate_property(split_container, "split_offset", split_container.split_offset, 0, 0.4, Tween.TRANS_QUAD, Tween.EASE_OUT)

In these functions, a tween is used to animate the ‘split_offset’ property to smoothly hide or show the left panel with a Quad transition and ease-out easing method.

In conclusion, the versatility of the SplitContainer in Godot 4 offers abundant opportunities for creating dynamic and responsive UIs. By understanding and utilizing its capabilities through code examples, you are equipped to design more engaging and user-friendly interfaces, allowing you to stand out in the competitive world of game development. Continue to explore and experiment with these features to elevate your Godot projects to new heights.

Continue Your Godot Development Journey

If you’ve enjoyed learning about the SplitContainer and the possibilities it opens up in Godot 4, don’t let your development journey end here. To further enhance your Godot skills and dive deeper into game development, we invite you to explore our Godot Game Development Mini-Degree. This program covers a vast range of topics, from mastering 2D and 3D assets to programming gameplay mechanics and building entire games from the ground up. Through project-based learning and live coding lessons, you will gain the hands-on experience necessary to grow your game development portfolio.

At Zenva, we provide a structured learning path that takes you from beginner to professional, with over 250 courses across various fields, including programming, game development, and AI. Learn at your own pace, earn certificates, and build practical skills that can propel your career forward. Whether you’re just starting out or looking to refine your expertise, our collection of Godot courses will support your learning goals and help you make your mark in the world of game development.

Embrace the opportunity to turn your creative ideas into reality—start with our Godot Game Development Mini-Degree or explore our broader range of Godot courses to find the perfect match for your learning journey. Your path to becoming a game developer begins with Zenva.


In the realm of Godot 4, mastery of UI components like the SplitContainer is a testament to your evolving skill set as a developer. These foundational elements are the building blocks that empower you to craft engaging, polished, and customized gaming experiences that resonate with your audience. With the practical knowledge you’ve gained and the code examples you’ve explored, the path forward is clear and promising. We encourage you to keep experimenting, learning, and growing.

The journey of learning never truly ends, especially in the fast-paced world of game development. Enhance your expertise and continue pushing the boundaries of what you can create with Godot by joining us at Zenva in our comprehensive Godot Game Development Mini-Degree. Let’s transform those sparks of imagination into the fires of inventive and immersive games together. With Zenva, the next chapter of your developer story is just one click away.

Python Blog Image

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