Up to date

This page is up to date for Godot 4.0. If you still find outdated information, please open an issue.

CheckButton

Inherits: Button < BaseButton < Control < CanvasItem < Node < Object

A button that represents a binary choice.

Description

CheckButton is a toggle button displayed as a check field. It’s similar to CheckBox in functionality, but it has a different appearance. To follow established UX patterns, it’s recommended to use CheckButton when toggling it has an immediate effect on something. For example, it can be used when pressing it shows or hides advanced settings, without asking the user to confirm this action.

See also BaseButton which contains common properties and methods associated with this node.

Properties

Theme Properties

Theme Property Descriptions

Color font_color = Color(0.875, 0.875, 0.875, 1)

The CheckButton text’s font color.

Color font_disabled_color = Color(0.875, 0.875, 0.875, 0.5)

The CheckButton text’s font color when it’s disabled.

Color font_focus_color = Color(0.95, 0.95, 0.95, 1)

The CheckButton text’s font color when it’s focused. Only replaces the normal text color of the button. Disabled, hovered, and pressed states take precedence over this color.

Color font_hover_color = Color(0.95, 0.95, 0.95, 1)

The CheckButton text’s font color when it’s hovered.

Color font_hover_pressed_color = Color(1, 1, 1, 1)

The CheckButton text’s font color when it’s hovered and pressed.

Color font_outline_color = Color(1, 1, 1, 1)

The tint of text outline of the CheckButton.

Color font_pressed_color = Color(1, 1, 1, 1)

The CheckButton text’s font color when it’s pressed.

int check_v_offset = 0

The vertical offset used when rendering the toggle icons (in pixels).

int h_separation = 4

The separation between the toggle icon and the text (in pixels). Negative values will be treated as 0 when used.

int outline_size = 0

The size of the text outline.

Note: If using a font with FontFile.multichannel_signed_distance_field enabled, its FontFile.msdf_pixel_range must be set to at least twice the value of outline_size for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended.

Font font

The Font to use for the CheckButton text.

int font_size

Font size of the CheckButton‘s text.

Texture2D checked

The icon to display when the CheckButton is checked (for left-to-right layouts).

Texture2D checked_disabled

The icon to display when the CheckButton is checked and disabled (for left-to-right layouts).

Texture2D checked_disabled_mirrored

The icon to display when the CheckButton is checked and disabled (for right-to-left layouts).

Texture2D checked_mirrored

The icon to display when the CheckButton is checked (for right-to-left layouts).

Texture2D unchecked

The icon to display when the CheckButton is unchecked (for left-to-right layouts).

Texture2D unchecked_disabled

The icon to display when the CheckButton is unchecked and disabled (for left-to-right layouts).

Texture2D unchecked_disabled_mirrored

The icon to display when the CheckButton is unchecked and disabled (for right-to-left layouts).

Texture2D unchecked_mirrored

The icon to display when the CheckButton is unchecked (for right-to-left layouts).

StyleBox disabled

The StyleBox to display as a background when the CheckButton is disabled.

StyleBox focus

The StyleBox to display as a background when the CheckButton is focused. The focus StyleBox is displayed over the base StyleBox, so a partially transparent StyleBox should be used to ensure the base StyleBox remains visible. A StyleBox that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a StyleBoxEmpty resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons.

StyleBox hover

The StyleBox to display as a background when the CheckButton is hovered.

StyleBox hover_pressed

The StyleBox to display as a background when the CheckButton is hovered and pressed.

StyleBox normal

The StyleBox to display as a background.

StyleBox pressed

The StyleBox to display as a background when the CheckButton is pressed.