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 FocusedIndicatorColor
Menu	MenuVisual	BackgroundColor
PasswordBox	PasswordBoxVisual	BackgroundColor ForegroundColor SelectionBackgroundColor Placeholder Color 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 Placeholder Color CaretColor FocusedIndicatorColor
Window	WindowVisual	Window

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. For more control over colors and states, see the Styling Using States page.