CheckButton in Godot – Complete Guide

Welcome to our tutorial on the CheckButton class in Godot 4, the popular open-source game engine. Whether you’re taking your first steps into game development or looking to refine your technical skills, learning how to implement user interface elements like CheckButtons can greatly enhance your projects. This versatile button allows for creating clear and intuitive interactions in your games and applications. Throughout this tutorial, you’ll discover just how useful CheckButtons can be and why mastering them is essential for any Godot developer.

What is CheckButton?

In Godot 4, a CheckButton is a specialized form of a button that represents a binary choice – it’s either in an “on” or “off” state. It serves as a toggle button with a distinctive check field appearance. Unlike the CheckBox, which it closely resembles in functionality, the CheckButton tends to have a different aesthetic, making it suitable for certain design choices in your game or application.

What is it for?

The primary use of a CheckButton is to offer a simple mechanism for users to make a binary choice with an immediate effect. It shines in scenarios where toggling the button should instantly trigger a change in the application without requiring further confirmation. For example, revealing advanced settings or toggling a game feature like music or sound effects on and off.

Why should I learn it?

Understanding how to use CheckButtons is crucial for creating interactive and user-friendly interfaces. They are a fundamental component in Godot’s rich UI system, and knowing how to customize them can make your game or application feel more polished. Moreover, they’re a part of many common game settings, making them an essential tool in a developer’s toolbox. By mastering CheckButtons, you’ll be capable of enhancing player experiences and streamlining navigation in your projects.

CTA Small Image

Adding a CheckButton to the Scene

First, let’s start by adding a CheckButton to our scene. You can do this by either dragging a CheckButton node into the scene tree or by adding it through code. Below is the simple process of how you might add it in the editor:

var check_button =

Setting Up the Label and Toggle State

Once you have your CheckButton added, you might want to customize its label and set its initial toggle state. You can use the `text` property to set the label and the `pressed` property to define whether the button starts in an ‘on’ (checked) or ‘off’ (unchecked) state:

check_button.text = "Enable Music"
check_button.pressed = true

Connecting to the “toggled” Signal

The CheckButton emits a signal called “toggled” whenever it is checked or unchecked. You’ll want to connect this signal to a function to perform the action you desire when the state changes. This can be done through the editor or through code as shown:

check_button.connect("toggled", self, "_on_CheckButton_toggled")

func _on_CheckButton_toggled(button_pressed):
    if button_pressed:
        print("CheckButton is now ON")
        print("CheckButton is now OFF")

Styling the CheckButton

To make the CheckButton fit with your game’s aesthetic, you might want to style it. You can do this by setting the `theme` property or by directly modifying its `styles`:

var style_normal =
style_normal.bg_color = Color(0.25, 0.25, 0.25)
check_button.add_stylebox_override("normal", style_normal)

var style_pressed =
style_pressed.bg_color = Color(0.45, 0.45, 0.45)
check_button.add_stylebox_override("pressed", style_pressed)

These code snippets only scratch the surface, yet they cover the fundamental aspects of CheckButtons you need to understand as you dive deeper into Godot 4’s UI system. In the next part, we’ll look at some more advanced features and practical examples of how CheckButtons can be used within your games and applications.

Great! Now that you have a foundational understanding of CheckButtons, let’s dive into more advanced features and how they can be utilized in your Godot 4 projects.

Customizing user interactions is important. For instance, you may want your CheckButton only to be toggled when certain conditions in your game are met. You can control the CheckButton’s ability to be pressed by adjusting its ‘disabled’ property:

check_button.disabled = true  // The CheckButton cannot be toggled
check_button.disabled = false // The CheckButton can now be toggled

Another useful feature is implementing groups for radio-button behavior, where turning one on would automatically turn the others off. You can achieve this by adding CheckButtons to a ButtonGroup:

var button_group =
check_button1.button_group = button_group
check_button2.button_group = button_group
// Only one CheckButton in the group can be toggled at a time

To visually confirm what state your CheckButton is in, consider updating another UI element, like a Label, when the ‘toggled’ signal emits:

var status_label =

func _on_CheckButton_toggled(button_pressed):
    if button_pressed:
        status_label.text = "Music Enabled"
        status_label.text = "Music Disabled"

Remember that the user interface should provide immediate and clear feedback. You could, for example, have the volume of the background music react in real-time as the CheckButton is toggled:

func _on_CheckButton_toggled(button_pressed):
    var volume_db = button_pressed ? 0 : -80  // On is full volume, Off is muted
    AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), volume_db)

Moreover, you might want your CheckButton’s state to persist across sessions. You can do this by saving the state to a config file when the ‘toggled’ signal is emitted and loading this state when initiating the button:

var config =

func save_checkbutton_state():
    config.set_value("settings", "enable_music", check_button.pressed)"user://settings.cfg")

func load_checkbutton_state():
    var err = config.load("user://settings.cfg")
    if err == OK:
        check_button.pressed = config.get_value("settings", "enable_music", true)

func _ready():

func _on_CheckButton_toggled(button_pressed):

Lastly, if you’re dealing with a complex UI, it might be important to identify which CheckButton was interacted with when connected to a single callback:

func _on_CheckButton_toggled(button_pressed, button_id):
    match button_id:

check_button1.connect("toggled", self, "_on_CheckButton_toggled", ["music_toggle"])
check_button2.connect("toggled", self, "_on_CheckButton_toggled", ["sfx_toggle"])

These examples demonstrate the versatility of CheckButtons within your Godot 4 UI. Whether it’s ensuring accessible game settings or enabling advanced customization, mastering CheckButtons opens the door to creating more dynamic and user-friendly experiences in your projects. We encourage you to play around with these concepts and integrate them into your Godot endeavors. Happy coding!

We’ve already covered a lot of ground with CheckButtons, but there’s plenty more we can do to ensure our game’s user interface is both functional and attractive. Here’s more on how to harness the full potential of CheckButtons in Godot 4.

Let’s start with customizing the icon that appears in a CheckButton. You might want an icon that better suits the aesthetics of your game. This can be done by setting the icon’s texture:

var check_icon = preload("res://path_to_your_icon.png")

Animations can add a touch of finesse to your UI. Here’s how you might animate a CheckButton when it’s toggled:

func _on_CheckButton_toggled(button_pressed):
    var tween =
    tween.interpolate_property(check_button, "rect_scale", 
                                Vector2(1, 1), Vector2(1.2, 1.2), 0.1, 
                                Tween.TRANS_BOUNCE, Tween.EASE_OUT)
    yield(tween, "tween_completed")
    tween.interpolate_property(check_button, "rect_scale", 
                                Vector2(1.2, 1.2), Vector2(1, 1), 0.1, 
                                Tween.TRANS_BOUNCE, Tween.EASE_OUT)

Themes in Godot are powerful, allowing for granular control over the appearance of all UI elements. If you’re styling multiple CheckButtons or other UI elements, here’s how you might create a theme to apply across all of them:

var theme =
var stylebox =
// Customize your stylebox...
theme.set_stylebox("normal", "CheckButton", stylebox)
// Apply theme to all CheckButtons
for check_button in get_tree().get_nodes_in_group("check_buttons"):
    check_button.theme = theme

It’s often good to have visual cues for interaction. You can highlight a CheckButton when it’s hovered over with a mouse:

func _on_CheckButton_mouse_entered():
    check_button.add_color_override("font_color_hover", Color(1, 1, 0))

func _on_CheckButton_mouse_exited():
    check_button.add_color_override("font_color_hover", Color(1, 1, 1))

Additionally, you can have CheckButton’s state influence the visibility of other nodes in the scene:

var advanced_options_panel = get_node("AdvancedOptionsPanel")

func _on_CheckButton_toggled(button_pressed):
    advanced_options_panel.visible = button_pressed

Incorporating sound feedback can enhance the tactile feel of UI elements. Play a sound effect when your CheckButton is toggled by using an AudioStreamPlayer node:

var click_sound = preload("res://click_sound.ogg")
var sound_player =

func _on_CheckButton_toggled(button_pressed): = click_sound

Fine control over CheckButton interaction can be achieved by disabling specific events, like clicks, while keeping others, like mouse-over, active:

func disable_checkbutton_clicks():
func enable_checkbutton_clicks():

By exploring these code examples, you can add life and interactivity to your CheckButtons, making them not only functional but an integral part of the user experience in your Godot projects. This deeper understanding enables you to create more engaging and intuitive interfaces. Remember that experimentation is key, so let these snippets be the start of your journey into advanced UI design with Godot 4’s CheckButtons. Happy designing!

Continuing Your Godot Learning Journey

The world of game development is vast and ever-changing, and your journey has just begun. If you’re feeling inspired and ready to delve deeper into the endless possibilities of Godot 4, we invite you to explore our Godot Game Development Mini-Degree. This comprehensive collection of courses has been carefully curated to take you from beginner to professional, enhancing your skills and helping you build a solid portfolio of projects.

Our Mini-Degree is a flexible learning path that allows you to dive into various aspects of game development, including 2D and 3D assets, GDScript, gameplay control flow, combat systems, and much more. With our high-quality content and experienced course creators, you can access our courses anytime, on any device, and at your own pace.

If you’re looking to broaden your horizons even further, don’t hesitate to check out our full range of Godot courses. No matter where you are in your learning journey, Zenva is here to support you every step of the way. Embrace the adventure ahead, and let’s create some amazing games together!


In wrapping up this tutorial, we hope you’ve gained valuable insight into the practical uses of CheckButtons in Godot 4. Implementing these versatile UI elements can dramatically elevate the interactivity and polish of your game projects. Beyond the basics, we’ve demonstrated some advanced techniques to enrich user interfaces, laying the foundation for you to create truly professional and engaging games.

At Zenva, we’re committed to providing you with the knowledge and resources to turn your game development aspirations into reality. Continue exploring, experimenting, and learning with our Godot Game Development Mini-Degree, where your creativity can reach new heights and your skills can truly shine. Happy coding, and here’s to the incredible games you’ll create!

Python Blog Image

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