Styling Individual Controls

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

Individual controls can be styled through their Visual property. By casting the Visual property to the control-specific type, color values can be assigned on a control.

Accessing Strongly-Typed Visual

Every control includes a Visual type which can be casted to access control-specific values. The type of each visual is the same name as the control, with the word Visual appended.

The following table shows which visuals and properties are available for each type of control:

Control	Visual	Styling Properties
Button	ButtonVisual	BackgroundColor FocusedIndicatorColor ForegroundColor
CheckBox	CheckBoxVisual	BackgroundColor FocusedIndicatorColor ForegroundColor CheckColor
ComboBox	ComboBoxVisual	BackgroundColor FocusedIndicatorColor ForegroundColor DropdownIndicatorColor
ItemsControl	ItemsControlVisual	BackgroundColor FocusedIndicatorColor
Label	LabelVisual	Color
ListBoxItem	ListBoxItemVisual	HighlightedBackgroundColor SelectedBackgroundColor ForegroundColor FocusedIndicatorColor
ListBox	ListBoxVisual	BackgroundColor FocusedIndicatorColor
Menuitem	MenuItemVisual	HighlightedBackgroundColor SelectedBackgroundColor ForegroundColor SubmenuIndicatorColor
Menu	MenuVisual	BackgroundColor
PasswordBox	PasswordBoxVisual	BackgroundColor ForegroundColor SelectionBackgroundColor PlaceholderColor CaretColor FocusedIndicatorColor
RadioButton	RadioButtonVisual	BackgroundColor ForegroundColor RadioColor FocusedIndicatorColor
ScrollBar	ScrollBarVisual	TrackBackgroundColor ScrollArrowColor
ScrollViewer	ScrollViewerVisual	BackgroundColor FocusedIndicatorColor
Slider	SliderVisual	BackgroundColor TrackBackgroundColor FocusedIndicatorColor
Splitter	SplitterVisual	BackgroundColor
TextBox	TextBoxVisual	BackgroundColor ForegroundColor SelectionBackgroundColor PlaceholderColor CaretColor FocusedIndicatorColor
Window	WindowVisual	BackgroundColor

Code Example: Changing BackgroundColor

The following code shows how to access the Visual on a Button and TextBox to change the background color of each control:

var button = new Button();
button.AddToRoot();
var buttonVisual = (ButtonVisual)button.Visual;
buttonVisual.BackgroundColor = Color.Red;

var textBox = new TextBox();
textBox.AddToRoot();
textBox.Y = 32;
var textBoxVisual = (TextBoxVisual)textBox.Visual;
textBoxVisual.BackgroundColor = Color.Blue;

V3 Visuals no longer require changing colors on each individual state. By changing values like BackgroundColor, the visual automatically uses the color for other states such as Highlighted and Pushed.

Color Properties vs Visual Element Properties

Each color property listed above ultimately sets the color of one of the parts of a control. These individual parts are also accessible through the casted visual Visual, but usually these color values should not be directly changed. Setting a property directly on a visual may only be temporary - colors can be reset in response to actions such as highlight, push, or variable changes such as IsEnabled.

For example, the following code sets the Background.Color property on a Button, and this seems to change the color; however, the background color resets back when the user hovers over the button.

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

Color is only temporary - hover resets the color back to BackgroundColor

Since ButtonVisual exposes a BackgroundColor property, this should be used rather than directly setting the Background.Color value. In general, it's best to check if a color property already exists before making any changes to a Visual's child.

Changing Background Texture (NineSlice)

Most forms controls use a background which draws a texture using NineSlice. Gum provides a number of built-in styles for backgrounds which can be swapped by accessing the Visual's Background property.

The following table provides the names of the background objects for each control type:

Visual Type	Background(s)
ButtonVisual	Background
CheckBoxVisual	CheckBoxBackground (NineSlice displaying the check when selected)
ComboBoxVisual	Background (main background) ListBoxInstance.Background (dropdown background)
ItemsControlVisual	Background
LabelVisual	<No Background>
ListBoxItemVisual	Background (only visible when highlighted or selected)
ListBoxVisual	Background
MenuItemVisual	Background (only visible when highlighted or selected) Dropdown background can be controlled through a VisualTemplate as discussed in the Customizing Menu and MenuItem page
MenuVisual	Background
PasswordBoxVisual	Background SelectionInstance
RadioButtonVisual	RadioBackground (NineSlice displaying the Radio when selected)
ScrollBarVisual	TrackInstance UpButtonInstance.Background DownButtonInstance.Background ThumbInstance.Background
ScrollViewerVisual	Background
SliderVisual	TrackBackground
SplitterVisual	Background
TextBoxVisual	Background SelectionInstance
WindowVisual	Background

The background for a control's Visual can be modified using the built-in background styles, as shown in the following code:

var panel = new Panel();
panel.AddToRoot();
panel.Anchor(Anchor.Center);
panel.Width = 720;
panel.WidthUnits = DimensionUnitType.Absolute;
panel.Height = 220;
panel.HeightUnits = DimensionUnitType.Absolute;
panel.Visual.ChildrenLayout = ChildrenLayout.AutoGridHorizontal;
panel.Visual.AutoGridHorizontalCells = 4;
panel.Visual.AutoGridVerticalCells = 4;

AddButton(Styling.ActiveStyle.NineSlice.Solid);
AddButton(Styling.ActiveStyle.NineSlice.Bordered);
AddButton(Styling.ActiveStyle.NineSlice.BracketVertical);
AddButton(Styling.ActiveStyle.NineSlice.BracketHorizontal);
AddButton(Styling.ActiveStyle.NineSlice.Tab);
AddButton(Styling.ActiveStyle.NineSlice.TabBordered);
AddButton(Styling.ActiveStyle.NineSlice.Outlined);
AddButton(Styling.ActiveStyle.NineSlice.OutlinedHeavy);
AddButton(Styling.ActiveStyle.NineSlice.Panel);
AddButton(Styling.ActiveStyle.NineSlice.CircleSolid);
AddButton(Styling.ActiveStyle.NineSlice.CircleBordered);
AddButton(Styling.ActiveStyle.NineSlice.CircleOutlined);
AddButton(Styling.ActiveStyle.NineSlice.CircleOutlinedHeavy);

void AddButton(StateSave backgroundStyle)
{
    var button = new Button();
    button.Text = backgroundStyle.Name;
    button.Width = 168;
    panel.AddChild(button);

    var visual = (ButtonVisual)button.Visual;

    visual.Background.ApplyState(backgroundStyle);
}

Using Custom NineSlice Textures

A control's background NineSliceRuntime can be modified to reference a custom texture. For example, we can create a custom button using this texture:

To use this texture on a button, first save the texture in the folder where you keep your content. For example, save the file in your game's Content folder.

You can load this texture however you load other textures in your project, or you can use Gum's built-in content loading.

var texture = GumService.Default.ContentLoader.LoadContent<Texture2D>(
    "input_outline_square.png");

Once you have the texture loaded, you can use this on any control's background, a shown in the following code:

var texture = GumService.Default.ContentLoader.LoadContent<Texture2D>(
    "input_outline_square.png");

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

var visual = (ButtonVisual)button.Visual;
visual.Background.Texture = texture;
visual.Background.TextureAddress = TextureAddress.EntireTexture;

Notice that the button still uses its default coloring. This can be changed as shown in the following code:

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

var visual = (ButtonVisual)button.Visual;
visual.Background.Texture = texture;
visual.Background.TextureAddress = TextureAddress.EntireTexture;
visual.BackgroundColor = Color.Red;

For more information on working with NineSliceRuntime, see the NineSliceRuntime page.

Gum colors its controls by multiplying the texture color by the BackgroundColor. Therefore, if you intend to use BackgroundColor, it's best to use a white or grayscale texture.

If you prefer to use a texture that is not grayscale, you should set the BackgroundColor to White so that it is not tinted by Gum.

Advanced styling

For more control over colors and states, see the Styling Using States page.