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
ToggleButton	ToggleButtonVisual	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	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:

// Initialize
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.

// Initialize
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.

Visual Children Reference

Each V3 Visual is composed of named child elements that can be accessed as properties on the casted Visual. The following table lists all children for each Visual type. Where a child is covered by one of the styling color properties listed above, the corresponding property is noted — prefer using the styling property rather than setting colors directly on the child, unless you are building custom states.

This table documents V3 visuals. If your project uses V2 visuals, these property names may differ.

Visual Type	Child Name	Type	Styling Property
ButtonVisual	Background	NineSliceRuntime	BackgroundColor
ButtonVisual	TextInstance	TextRuntime	ForegroundColor
ButtonVisual	FocusedIndicator	NineSliceRuntime	FocusedIndicatorColor
ToggleButtonVisual	Background	NineSliceRuntime	BackgroundColor
ToggleButtonVisual	TextInstance	TextRuntime	ForegroundColor
ToggleButtonVisual	FocusedIndicator	NineSliceRuntime	FocusedIndicatorColor
CheckBoxVisual	CheckBoxBackground	NineSliceRuntime	BackgroundColor
CheckBoxVisual	InnerCheck (child of CheckBoxBackground)	SpriteRuntime	CheckColor
CheckBoxVisual	TextInstance	TextRuntime	ForegroundColor
CheckBoxVisual	FocusedIndicator	NineSliceRuntime	FocusedIndicatorColor
ComboBoxVisual	Background	NineSliceRuntime	BackgroundColor
ComboBoxVisual	TextInstance	TextRuntime	ForegroundColor
ComboBoxVisual	ListBoxInstance	ListBoxVisual	—
ComboBoxVisual	DropdownIndicator	SpriteRuntime	DropdownIndicatorColor
ComboBoxVisual	FocusedIndicator	NineSliceRuntime	FocusedIndicatorColor
ItemsControlVisual	Inherits all children from ScrollViewerVisual
LabelVisual	Inherits from TextRuntime directly, no children. Color is set via the Color styling property.
ListBoxItemVisual	Background	NineSliceRuntime	HighlightedBackgroundColor / SelectedBackgroundColor
ListBoxItemVisual	TextInstance	TextRuntime	ForegroundColor
ListBoxItemVisual	FocusedIndicator	NineSliceRuntime	FocusedIndicatorColor
ListBoxVisual	Background	NineSliceRuntime	BackgroundColor
ListBoxVisual	FocusedIndicator	NineSliceRuntime	FocusedIndicatorColor
ListBoxVisual	ClipAndScrollContainer	ContainerRuntime	—
ListBoxVisual	VerticalScrollBarInstance (child of ClipAndScrollContainer)	ScrollBarVisual	—
ListBoxVisual	ClipContainerParent (child of ClipAndScrollContainer)	ContainerRuntime	—
ListBoxVisual	ClipContainerInstance (child of ClipContainerParent)	ContainerRuntime	—
ListBoxVisual	InnerPanelInstance (child of ClipContainerInstance)	ContainerRuntime	—
MenuItemVisual	Background	NineSliceRuntime	HighlightedBackgroundColor / SelectedBackgroundColor
MenuItemVisual	ContainerInstance	ContainerRuntime	—
MenuItemVisual	TextInstance (child of ContainerInstance)	TextRuntime	ForegroundColor
MenuItemVisual	SubmenuIndicatorInstance (child of ContainerInstance)	TextRuntime	SubmenuIndicatorColor
MenuVisual	Background	NineSliceRuntime	BackgroundColor
MenuVisual	InnerPanelInstance	ContainerRuntime	—
PasswordBoxVisual	Inherits all children from TextBoxBaseVisual
RadioButtonVisual	RadioBackground	NineSliceRuntime	BackgroundColor
RadioButtonVisual	Radio (child of RadioBackground)	SpriteRuntime	RadioColor
RadioButtonVisual	TextInstance	TextRuntime	ForegroundColor
RadioButtonVisual	FocusedIndicator	NineSliceRuntime	FocusedIndicatorColor
ScrollBarVisual	UpButtonInstance	ButtonVisual	—
ScrollBarVisual	UpButtonIcon (child of UpButtonInstance)	SpriteRuntime	ScrollArrowColor
ScrollBarVisual	DownButtonInstance	ButtonVisual	—
ScrollBarVisual	DownButtonIcon (child of DownButtonInstance)	SpriteRuntime	ScrollArrowColor
ScrollBarVisual	ThumbContainer	ContainerRuntime	—
ScrollBarVisual	TrackInstance (child of ThumbContainer)	NineSliceRuntime	TrackBackgroundColor
ScrollBarVisual	ThumbInstance (child of ThumbContainer)	ButtonVisual	—
ScrollViewerVisual	Background	NineSliceRuntime	BackgroundColor
ScrollViewerVisual	FocusedIndicator	NineSliceRuntime	FocusedIndicatorColor
ScrollViewerVisual	ScrollAndClipContainer	ContainerRuntime	—
ScrollViewerVisual	VerticalScrollBarInstance (child of ScrollAndClipContainer)	ScrollBarVisual	—
ScrollViewerVisual	HorizontalScrollBarInstance (child of ScrollAndClipContainer)	ScrollBarVisual	—
ScrollViewerVisual	ClipContainerContainer (child of ScrollAndClipContainer)	ContainerRuntime	—
ScrollViewerVisual	ClipContainerInstance (child of ClipContainerContainer)	ContainerRuntime	—
ScrollViewerVisual	InnerPanelInstance (child of ClipContainerInstance)	ContainerRuntime	—
SliderVisual	TrackInstance	ContainerRuntime	—
SliderVisual	TrackBackground (child of TrackInstance)	NineSliceRuntime	TrackBackgroundColor
SliderVisual	ThumbInstance (child of TrackInstance)	ButtonVisual	—
SliderVisual	FocusedIndicator	NineSliceRuntime	FocusedIndicatorColor
SplitterVisual	Background	NineSliceRuntime	BackgroundColor
TextBoxVisual	Inherits all children from TextBoxBaseVisual
TextBoxBaseVisual	Background	NineSliceRuntime	BackgroundColor
TextBoxBaseVisual	ClipContainer	ContainerRuntime	—
TextBoxBaseVisual	SelectionInstance (child of ClipContainer)	NineSliceRuntime	SelectionBackgroundColor
TextBoxBaseVisual	TextInstance (child of ClipContainer)	TextRuntime	ForegroundColor
TextBoxBaseVisual	PlaceholderTextInstance (child of ClipContainer)	TextRuntime	PlaceholderColor
TextBoxBaseVisual	CaretInstance (child of ClipContainer)	SpriteRuntime	CaretColor
TextBoxBaseVisual	FocusedIndicator	NineSliceRuntime	FocusedIndicatorColor
WindowVisual	Background	NineSliceRuntime	BackgroundColor
WindowVisual	InnerPanelInstance	Panel	—
WindowVisual	TitleBarInstance	Panel	—
WindowVisual	BorderTopLeftInstance	Panel	—
WindowVisual	BorderTopRightInstance	Panel	—
WindowVisual	BorderBottomLeftInstance	Panel	—
WindowVisual	BorderBottomRightInstance	Panel	—
WindowVisual	BorderTopInstance	Panel	—
WindowVisual	BorderBottomInstance	Panel	—
WindowVisual	BorderLeftInstance	Panel	—
WindowVisual	BorderRightInstance	Panel	—

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:

// Initialize
var panel = new Panel();
panel.AddToRoot();
panel.Anchor(Anchor.Center);
panel.Width = 720;
panel.WidthUnits = Gum.DataTypes.DimensionUnitType.Absolute;
panel.Height = 220;
panel.HeightUnits = Gum.DataTypes.DimensionUnitType.Absolute;
panel.Visual.ChildrenLayout = Gum.Managers.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.

// Initialize
var texture = GumUI.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:

// Initialize
var texture = GumUI.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:

// Initialize
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.