> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/code/styling/code-only-styling/styling-individual-controls.md).

# Styling Individual Controls

{% hint style="info" %}
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](/gum/gum-tool/upgrading/migrating-to-2025-november.md) page.
{% endhint %}

## 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:

<table><thead><tr><th>Control</th><th width="216.272705078125">Visual</th><th>Styling Properties</th></tr></thead><tbody><tr><td>Button</td><td>ButtonVisual</td><td><ul><li>BackgroundColor</li><li>FocusedIndicatorColor</li><li>ForegroundColor</li></ul></td></tr><tr><td>ToggleButton</td><td>ToggleButtonVisual</td><td><ul><li>BackgroundColor</li><li>FocusedIndicatorColor</li><li>ForegroundColor</li></ul></td></tr><tr><td>CheckBox</td><td>CheckBoxVisual</td><td><ul><li>BackgroundColor</li><li>FocusedIndicatorColor</li><li>ForegroundColor</li><li>CheckColor</li></ul></td></tr><tr><td>ComboBox</td><td>ComboBoxVisual</td><td><ul><li>BackgroundColor</li><li>FocusedIndicatorColor</li><li>ForegroundColor</li><li>DropdownIndicatorColor</li></ul></td></tr><tr><td>ItemsControl</td><td>ItemsControlVisual</td><td><ul><li>BackgroundColor</li><li>FocusedIndicatorColor</li></ul></td></tr><tr><td>Label</td><td>LabelVisual</td><td><ul><li>Color</li></ul></td></tr><tr><td>ListBoxItem</td><td>ListBoxItemVisual</td><td><ul><li>HighlightedBackgroundColor</li><li>SelectedBackgroundColor</li><li>ForegroundColor</li><li>FocusedIndicatorColor</li></ul></td></tr><tr><td>ListBox</td><td>ListBoxVisual</td><td><ul><li>BackgroundColor</li><li>FocusedIndicatorColor</li></ul></td></tr><tr><td>Menuitem</td><td>MenuItemVisual</td><td><ul><li>HighlightedBackgroundColor</li><li>SelectedBackgroundColor</li><li>ForegroundColor</li><li>SubmenuIndicatorColor</li></ul></td></tr><tr><td>Menu</td><td>MenuVisual</td><td><ul><li>BackgroundColor</li></ul></td></tr><tr><td>PasswordBox</td><td>PasswordBoxVisual</td><td><ul><li>BackgroundColor</li><li>ForegroundColor</li><li>SelectionBackgroundColor</li><li>PlaceholderColor</li><li>CaretColor</li><li>FocusedIndicatorColor</li></ul></td></tr><tr><td>RadioButton</td><td>RadioButtonVisual</td><td><ul><li>BackgroundColor</li><li>ForegroundColor</li><li>RadioColor</li><li>FocusedIndicatorColor</li></ul></td></tr><tr><td>ScrollBar</td><td>ScrollBarVisual</td><td><ul><li>TrackBackgroundColor</li><li>ScrollArrowColor</li></ul></td></tr><tr><td>ScrollViewer</td><td>ScrollViewerVisual</td><td><ul><li>BackgroundColor</li><li>FocusedIndicatorColor</li></ul></td></tr><tr><td>Slider</td><td>SliderVisual</td><td><ul><li>TrackBackgroundColor</li><li>FocusedIndicatorColor</li></ul></td></tr><tr><td>Splitter</td><td>SplitterVisual</td><td><ul><li>BackgroundColor</li></ul></td></tr><tr><td>TextBox</td><td>TextBoxVisual</td><td><ul><li>BackgroundColor</li><li>ForegroundColor</li><li>SelectionBackgroundColor</li><li>PlaceholderColor</li><li>CaretColor</li><li>FocusedIndicatorColor</li></ul></td></tr><tr><td>Window</td><td>WindowVisual</td><td><ul><li>BackgroundColor</li></ul></td></tr></tbody></table>

## 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:

```csharp
// 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;
```

<figure><img src="/files/xRXKmIoAG10bG8WTsuan" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
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.
{% endhint %}

## 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.

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

<figure><img src="/files/WC2OMRAPLyhJINdnggKZ" alt=""><figcaption><p>Color is only <strong>temporary</strong> - hover resets the color back to BackgroundColor</p></figcaption></figure>

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.

{% hint style="info" %}
This table documents V3 visuals. If your project uses V2 visuals, these property names may differ.
{% endhint %}

| 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       | <ul><li>Background</li></ul>                                                                                                                                                                                                                     |
| CheckBoxVisual     | <ul><li>CheckBoxBackground (NineSlice displaying the check when selected)</li></ul>                                                                                                                                                              |
| ComboBoxVisual     | <ul><li>Background (main background)</li><li>ListBoxInstance.Background (dropdown background)</li></ul>                                                                                                                                          |
| ItemsControlVisual | <ul><li>Background</li></ul>                                                                                                                                                                                                                     |
| LabelVisual        | \<No Background>                                                                                                                                                                                                                                 |
| ListBoxItemVisual  | <ul><li>Background (only visible when highlighted or selected)</li></ul>                                                                                                                                                                         |
| ListBoxVisual      | <ul><li>Background</li></ul>                                                                                                                                                                                                                     |
| MenuItemVisual     | <ul><li>Background (only visible when highlighted or selected)</li><li>Dropdown background can be controlled through a VisualTemplate as discussed in the <a href="/pages/Hcnjfd34vwMQq8ndSWqK">Customizing Menu and MenuItem</a> page</li></ul> |
| MenuVisual         | <ul><li>Background</li></ul>                                                                                                                                                                                                                     |
| PasswordBoxVisual  | <ul><li>Background</li><li>SelectionInstance</li></ul>                                                                                                                                                                                           |
| RadioButtonVisual  | <ul><li>RadioBackground (NineSlice displaying the Radio when selected)</li></ul>                                                                                                                                                                 |
| ScrollBarVisual    | <ul><li>TrackInstance</li><li>UpButtonInstance.Background</li><li>DownButtonInstance.Background</li><li>ThumbInstance.Background</li></ul>                                                                                                       |
| ScrollViewerVisual | <ul><li>Background</li></ul>                                                                                                                                                                                                                     |
| SliderVisual       | <ul><li>TrackBackground</li></ul>                                                                                                                                                                                                                |
| SplitterVisual     | <ul><li>Background</li></ul>                                                                                                                                                                                                                     |
| TextBoxVisual      | <ul><li>Background</li><li>SelectionInstance</li></ul>                                                                                                                                                                                           |
| WindowVisual       | <ul><li>Background</li></ul>                                                                                                                                                                                                                     |

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

```csharp
// 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);
}
```

<figure><img src="/files/mY1vfxcwErl7ZWwaLx3G" alt=""><figcaption></figcaption></figure>

## 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:

<figure><img src="/files/jBF6EZ0mfYw6fjz9LlGd" alt=""><figcaption></figcaption></figure>

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.

```csharp
// 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:

```csharp
// 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;
```

<figure><img src="/files/ROn2K0B0lFigxJDvGcGA" alt=""><figcaption></figcaption></figure>

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

<pre class="language-csharp"><code class="lang-csharp">// 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;
<strong>visual.BackgroundColor = Color.Red;
</strong></code></pre>

<figure><img src="/files/awXgde5E2TP574KgmCaa" alt=""><figcaption></figcaption></figure>

For more information on working with NineSliceRuntime, see the [NineSliceRuntime](/gum/code/standard-visuals/ninesliceruntime.md) page.

{% hint style="info" %}
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.
{% endhint %}

## Advanced styling

For more control over colors and states, see the [Styling Using States](/gum/code/styling/code-only-styling/styling-using-states.md) page.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flatredball.com/gum/code/styling/code-only-styling/styling-individual-controls.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.