AspectRatioContainer in Godot – Complete Guide

When designing the user interface or even gameplay elements within a game, it’s crucial that everything looks just right on different screen sizes and aspect ratios. Have you ever wondered how you can make your game interfaces scale elegantly while maintaining their proportions? Enter the AspectRatioContainer in Godot 4, a powerful tool in the game developer’s toolbox. Join us as we dive into the world of responsive and proportionate design with AspectRatioContainer, and see how it can enhance the player experience in your games by ensuring consistency across various devices.

What is AspectRatioContainer?

The AspectRatioContainer is a class in the Godot 4 engine designed to maintain child controls’ aspect ratio regardless of the container’s size changes. This means you can resize your game window, or it can be displayed on various screen sizes, and the objects inside this container will adjust their size proportionally. It’s an essential element for responsive game design, where interfaces need to look good on any screen.

What is it for?

The AspectRatioContainer is used when you have elements like sprites, buttons, or panels that must retain their width and height ratios as the game window resizes. This is particularly useful in games that could be played on different devices such as smartphones, tablets, and desktop computers, ensuring a consistent user experience and aesthetic across the board.

Why Should I Learn It?

Understanding how AspectRatioContainer works and knowing how to implement it effectively in your projects equips you with the knowledge to create polished game interfaces that adapt to screen changes gracefully. By learning this class, you ensure that your game’s visual elements remain user-friendly and visually appealing no matter where your game is played, making this an invaluable skill in game development.

CTA Small Image

Creating an AspectRatioContainer

To begin implementing AspectRatioContainer in your Godot project, first ensure you have a scene where you wish to maintain the aspect ratio of the content. Add an AspectRatioContainer as a node in your scene by following these simple steps:

var aspect_ratio_container =

This creates a new instance of the AspectRatioContainer and adds it as a child to the current node.

Configuring the Properties

Once you have an AspectRatioContainer in your scene, you can set specific properties to configure its behavior. The rect_min_size property allows you to set the minimum size of the container, ensuring that it doesn’t get too small:

aspect_ratio_container.rect_min_size = Vector2(400, 300)

You can also define the aspect ratio you wish to maintain using the aspect property. For example, to keep a 16:9 aspect ratio, you would use:

aspect_ratio_container.aspect = AspectRatioContainer.ASPECT_WIDE

Alternatively, if you want to maintain the original aspect ratio of the child node, you should set:

aspect_ratio_container.aspect = AspectRatioContainer.ASPECT_KEEP

If you want to control what happens when the container is larger than the minimum size needed to maintain the aspect ratio, set the stretch_mode. For example, if you wish for the content to stay centered:

aspect_ratio_container.stretch_mode = AspectRatioContainer.STRETCH_CENTER

Adding Content to the AspectRatioContainer

Add a child node to the container that you want to maintain the aspect ratio for. This could be a texture, a button, or any other UI element. Here’s an example of how to add a TextureRect with an image while keeping the aspect fixed:

var texture_rect =
texture_rect.texture = preload("res://path_to_your_image.png")

Now the TextureRect will maintain its aspect ratio no matter how you resize the AspectRatioContainer or the game window.

Making Adjustments at Runtime

AspectRatioContainer can be adjusted at runtime to respond to user actions or changes within the game. For example, if you want to change the aspect ratio when a user clicks a button:

button.connect("pressed", self, "_on_Button_pressed")

func _on_Button_pressed():
    aspect_ratio_container.aspect = AspectRatioContainer.ASPECT_NARROW
    # This sets the aspect ratio to narrow (e.g., 4:3)

With this function, the aspect ratio of the elements within the container will change dynamically at runtime, providing a versatile user experience.

The AspectRatioContainer in Godot 4 is quite versatile, not only does it maintain the aspect ratio, but it also allows for various adjustments and dynamic changes as per the game’s needs. Here are additional examples and use cases that illustrate the flexibility of this container.

Firstly, if you want to change the stretch_mode to fill the entire container space while keeping the aspect ratio, you can do so:

aspect_ratio_container.stretch_mode = AspectRatioContainer.STRETCH_WIDTH
# This stretches the child nodes to fill the width of the container.

Conversely, to make the content stretch and fill the container’s height instead, the code would be:

aspect_ratio_container.stretch_mode = AspectRatioContainer.STRETCH_HEIGHT
# This stretches the child nodes to fill the height of the container.

Sometimes you may want to programmatically adjust the minimum size of the container. For instance, if a certain level in the game requires a different layout, you can set this on the fly:

aspect_ratio_container.rect_min_size = Vector2(800, 600)
# Now the minimum size of the AspectRatioContainer is 800 by 600 pixels.

If your game design includes responsive UI elements that need to adapt to landscape and portrait modes, AspectRatioContainer can help. Here is how you might check the orientation and adjust the aspect accordingly:

func _process(delta):
    if OS.window_size.x > OS.window_size.y:
        # Landscape orientation
        aspect_ratio_container.aspect = AspectRatioContainer.ASPECT_WIDE
        # Portrait orientation
        aspect_ratio_container.aspect = AspectRatioContainer.ASPECT_NARROW

Furthermore, if you are looking to animate the container’s size, you could leverage the animation player in Godot:

var anim_player =

var animation =
animation.track_insert_key(0, "rect_min_size", Vector2(800, 600))
animation.length = 1 # The animation will take 1 second.

anim_player.add_animation("resize_container", animation)"resize_container")
# This will animate the AspectRatioContainer to a min size of 800x600 over 1 second.

The AspectRatioContainer can also be nested. For complex UI designs with multiple nested elements, you can contain them within different AspectRatioContainers to ensure that each maintains its correct proportions:

var child_aspect_ratio_container =
child_aspect_ratio_container.aspect = AspectRatioContainer.ASPECT_KEEP

var texture_rect_2 =
texture_rect_2.texture = preload("res://path_to_another_image.png")
# The inner container now maintains the aspect ratio of 'texture_rect_2'.

These code snippets highlight the AspectRatioContainer’s ability to maintain consistent UI elements. We recognize that responsive design is key to crafting an immersive and enjoyable user experience, ensuring that your games look and behave as intended across all plays.

When working with AspectRatioContainer, it’s not just about maintaining aspect ratio but also ensuring the content is properly aligned within the container. In Godot 4, the Alignment enumeration allows you to align your content horizontally and vertically within the container. Here’s how you might center content both horizontally and vertically:

aspect_ratio_container.alignment_horizontal = AspectRatioContainer.ALIGN_CENTER
aspect_ratio_container.alignment_vertical = AspectRatioContainer.ALIGN_CENTER
# This centers the child node inside the AspectRatioContainer.

Now, let’s consider a situation where you need to toggle the visibility of the container based on game events, such as displaying a menu on a pause action. You can accomplish this with:

func _on_pause_button_pressed():
    aspect_ratio_container.visible = !aspect_ratio_container.visible
# This toggles the visibility of the AspectRatioContainer and its children.

At times, you might need to dynamically load and display images with varying sizes in an AspectRatioContainer. The following example demonstrates loading an image at runtime and adding it as a child:

func _load_image(image_path):
    var texture =
    var image =
    var texture_rect =
    texture_rect.texture = texture
# This loads an image, sets it as a texture, and adds a TextureRect to the container.

If your game design calls for AspectRatioContainer nodes that are only present under certain conditions, like during a tutorial or a specific game level, you can instantiate and set them up in code as well:

func _create_tutorial_ui():
    var tutorial_container =
    tutorial_container.aspect = AspectRatioContainer.ASPECT_KEEP
    tutorial_container.stretch_mode = AspectRatioContainer.STRETCH_CENTER
    var tutorial_sprite =
    tutorial_sprite.texture = preload("res://tutorial_image.png")
# This creates a new AspectRatioContainer with a sprite for tutorial purposes.

When multiple UI elements are involved, such as a dynamic inventory system, you can iterate through a list of items and add them to an AspectRatioContainer to maintain a uniform appearance:

for item_texture in inventory_items:
    var item_sprite =
    item_sprite.texture = item_texture
# Loops through a list of item textures and adds each as a Sprite to the container.

Finally, if you’re creating a responsive grid of items, such as for a character selection screen, you can create multiple AspectRatioContainers inside a GridContainer for a responsive, grid-based layout:

var grid_container =
grid_container.columns = 3 # Set the number of columns for the grid.
for character_texture in character_portraits:
    var character_container =
    character_container.aspect = AspectRatioContainer.ASPECT_KEEP
    var character_sprite =
    character_sprite.texture = character_texture
# Creates a grid of characters with maintained aspect ratios.

Through these examples, we see how the AspectRatioContainer can manage a variety of elements and scenarios, making it a versatile component for UI and game element design in Godot. From aligning and animating to dynamically loading and organizing content, it caters to a myriad of design necessities, further empowering game developers to craft visually consistent and professional experiences for players across all screen sizes.

Where to Go Next in Your Godot Learning Journey

Embarking on the journey of game development can be an immensely rewarding experience. Having experimented with the AspectRatioContainer in Godot 4, you’ve taken a significant step forward in mastering responsive UI design for your games. But your learning doesn’t have to stop here.

To further enhance your skills and dive deeper into the powerful capabilities of the Godot engine, we invite you to explore our Godot Game Development Mini-Degree. This comprehensive collection of courses offers a curated learning path from the basics to more complex game development concepts. By venturing through our Mini-Degree, you’ll gain hands-on experience with practical projects, strengthen your understanding of GDScript, and learn to create compelling gameplay experiences for various game genres.

If you’re eager for more and want to broaden your Godot expertise, check out our full array of Godot courses. These lessons cater to learners at all levels, from those just starting out to seasoned developers looking to refine their skills. At Zenva, we are passionate about empowering you to create, innovate, and bring your game development visions to life.


As you continue experimenting and building in the Godot engine, remember that the AspectRatioContainer is just one of many tools at your disposal. It’s a testament to the flexibility and depth that Godot offers, allowing creators like you to craft experiences that resonate with players on any device. At Zenva, we’re committed to guiding you through every step of your game development journey, providing the knowledge and resources you need to turn your creative vision into reality.

We encourage you to delve even deeper into what Godot has to offer by joining our Godot Game Development Mini-Degree. Whether you’re honing your craft or just beginning to scratch the surface of what’s possible, our courses are designed to give you a competitive edge in the evolving landscape of game development. Continue learning, keep growing, and unleash the full potential of your game development talents with Zenva.

Python Blog Image

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