Styling Using States

This document assumes using V3 styles, which were introduced at the end of November 2025. If your project is using V2 visuals, you need to upgrade to V3 before the styling discussed on this document can be used.

For information on upgrading, see the Migrating to 2025 November page.

Introduction

Gum controls respond to cursor and input actions by changing their appearance. States can be used to customize how controls react to these actions.

Each control provides states through its Visual object. Once a Visual is casted to its specific type, its states can be customized.

For more information about Visuals, see the Styling Individual Controls page.

Accessing Strongly-Typed States

The following table lists the states available for each control type:

Visual Type	States
ButtonVisual	Disabled DisabledFocused Enabled Focused Highlighted HighlightedFocused Pushed
CheckBoxVisual	DisabledOn / Off / Indeterminate DisabledFocusedOn / Off / Indeterminate EnabledOn / Off / Indeterminate FocusedOn / Off / Indeterminate HighlightedOn / Off / Indeterminate HighlightedFocusedOn / Off / Indeterminate PushedOn / Off / Indeterminate
ComboBoxVisual	Disabled DisabledFocused Enabled Focused Highlighted HighlightedFocused Pushed
ItemsControlVisual	Enabled Focused
LabelVisual	<No States>
ListBoxItemVisual	Disabled Enabled Focused Highlighted Selected
ListBoxVisual	Disabled DisabledFocused Enabled Focused Highlighted HighlightedFocused Pushed
MenuItemVisual	Disabled Enabled Focused Highlighted Selected
MenuVisual	<No States>
PasswordBoxVisual	Disabled Enabled Focused Highlighted PasswordBoxVisual also includes states for single and multi-line layouts, but these states are not covered in this document.
RadioButtonVisual	DisabledOn / Off DisabledFocusedOn / Off EnabledOn / Off FocusedOn / Off HighlightedOn / Off HighlightedFocusedOn / Off Pushed On / Off
ScrollBarVisual	<No Color-related States> ScrollBar includes states for Vertical and Horizontal alignment, but these states are not covered in this document.
ScrollViewerVisual	Enabled Focused
SliderVisual	Disabled DisabledFocused Enabled Focused Highlighted HighlightedPushed Pushed
SplitterVisual	<No States>
TextBoxVisual	Disabled Enabled Focused Highlighted TextBoxVisual also includes states for single and multi-line layouts, but these states are not covered in this document.
WindowVisual	<No States>

Each control provides states for common situations. If your game requires additional state support, please let us know on GitHub or Discord.

Code Example: Setting States on a ButtonVisual

To change how a control displays itself using states, the following steps must be performed:

1. Cast the Visual of the control to the appropriate Visual type

2. Clear the state that you would like to change

3. Assign the behavior of the state by setting its Apply or filling its Variables

The following code shows how to change a button so that its colors are explicitly set when highlighted, pressed, or in its default (Enabled) state.

var button = new Button();
button.AddToRoot();
button.Anchor(Anchor.Center);
var buttonVisual = (ButtonVisual)button.Visual;

var enabledState = buttonVisual.States.Enabled;
enabledState.Clear();
enabledState.Apply = () =>
{
    buttonVisual.Background.Color = Color.Green;
};

var pushedState = buttonVisual.States.Pushed;
pushedState.Clear();
pushedState.Apply = () =>
{
    buttonVisual.Background.Color = Color.DarkBlue;
};

var highlightedState = buttonVisual.States.Highlighted;
highlightedState.Clear();
highlightedState.Apply = () =>
{
    buttonVisual.Background.Color = Color.Yellow;
};

// forcably apply the states to see the effect immediately
button.UpdateState();

Button applying color states

Although the default states only modify color, custom states are free to modify any property on the Visual. For example, the following code shows how to also modify the button's text size and increase the background size.

var button = new Button();
button.AddToRoot();
button.Anchor(Anchor.Center);
var buttonVisual = (ButtonVisual)button.Visual;

var enabledState = buttonVisual.States.Enabled;
enabledState.Clear();
enabledState.Apply = () =>
{
    buttonVisual.TextInstance.FontScale = 1;
    buttonVisual.Background.Width = 0;
    buttonVisual.Background.Height = 0;
};

var pushedState = buttonVisual.States.Pushed;
pushedState.Clear();
pushedState.Apply = () =>
{
    buttonVisual.TextInstance.FontScale = 1;
    buttonVisual.Background.Width = -4;
    buttonVisual.Background.Height = -4;
};

var highlightedState = buttonVisual.States.Highlighted;
highlightedState.Clear();
highlightedState.Apply = () =>
{
    buttonVisual.TextInstance.FontScale = 1.3f;
    buttonVisual.Background.Width = 2;
    buttonVisual.Background.Height = 2;
};

Button changing its background and text size through states

Any property on a control's Visual can be changed through state. For more information on working with the standard visual types which make up controls, see the Standard Visuals page.