Styling Using ActiveStyles

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 can be restyled using an ActiveStyle object. Changes to ActiveStyle result in style changes for all controls created after the change is made. ActiveStyle can make it easy to restyle all controls without needing to make changes to each individual control.

Styling.ActiveStyle.Colors

Gum includes a Styling object which contains multiple color values for default styling. For example the Primary color can be changed using the following code:

Styling.ActiveStyle.Colors.Primary = Color.DarkGreen;

The following properties exist on Colors:

Colors Property	Used By
Primary	Button Background CheckBox Background ComboBox DropdownIndicator ListBoxItem Background (Selected) MenuItem Background (Selected) RadioButton Background Slider Thumb Background TextBox Caret Window Background (Default only border)
Warning	FocusIndicators on all controls
Accent	ListBoxItem Background (Highlight) MenuItem Background (Highlight)
InputBackground	ComboBox Background ListBox Background Menu Background PasswordBox Background ScrollViewer Background Slider Track Background Splitter Background TextBox Background
SurfaceVariant	ScrollBar Track Background
IconDefault	CheckBox Check RadioButton Radio ScrollBar UpButton/DownButton Icon
TextPrimary	Button Text CheckBox Text ComboBox Text Label ListBoxItem Text MenuItem Text MenuItem SubmenuIndicator PasswordBox Text RadioButton Text TextBox Text
TextMuted	PasswordBox PlaceholderTextInstance TextBox PlaceholderTextInstance

Code Example: Applying Styles Before Creating Controls

The Styling.ActiveStyle.Color property includes styles that are used by controls when they are created. We can see how these affect controls by creating a sample project:

protected override void Initialize()
{
    GumUI.Initialize(this, DefaultVisualsVersion.V3);

    var window = new Window();
    window.AddToRoot();
    window.Anchor(Anchor.Center);
    window.Width = 270;
    window.MinWidth = 270;
    window.Height = 400;
    window.MinHeight = 400;

    var windowVisual = (WindowVisual)window.Visual;

    var stackPanel = new StackPanel();
    window.AddChild(stackPanel);
    stackPanel.Dock(Dock.Top);
    stackPanel.Y = window.TitleHeight;
    stackPanel.Width = -16;

    var button = new Button();
    var buttonVisual = (Gum.Forms.DefaultVisuals.V3.ButtonVisual)button.Visual;
    stackPanel.AddChild(button);

    var checkBox = new CheckBox();
    stackPanel.AddChild(checkBox);

    var comboBox = new ComboBox();
    stackPanel.AddChild(comboBox);
    for(int i = 0; i < 10; i++)
    {
        comboBox.Items.Add($"ComboBox Item {i}");
    }

    var listBox = new ListBox();
    stackPanel.AddChild(listBox);
    listBox.Height = 200;
    for(int i = 0; i < 20; i++)
    {
        listBox.Items.Add($"Item {i}");
    }

    var radioButton1 = new RadioButton();
    stackPanel.AddChild(radioButton1);
    radioButton1.Text = "Option 1";

    var radioButton2 = new RadioButton();
    stackPanel.AddChild(radioButton2);
    radioButton2.Text = "Option 2";

    var textBox = new TextBox();
    stackPanel.AddChild(textBox);
}

This code produces a set of controls which can be used to check how styling is applied.

Controls using default styles

Controls using default styles (Animated)

We can prefix the following code before creating all of our controls:

protected override void Initialize()
{
    GumUI.Initialize(this, DefaultVisualsVersion.V3);

    Styling.ActiveStyle.Colors.Primary = Color.DarkGreen;
    Styling.ActiveStyle.Colors.InputBackground = Color.Black;
    Styling.ActiveStyle.Colors.TextPrimary = Color.LimeGreen;
    Styling.ActiveStyle.Colors.Accent = Color.Yellow;

    // Create controls here:

By changing these colors, controls are created using the new colors:

Colors changed with minimal code

All Styling behaviors remain (darken/lighten)

Styling and Creation Order

Styling only applies after it has been set. Controls which are created before styling is set do not automatically update to the new style. The following code shows how order can impact how styling is assigned:

var stackPanel = new StackPanel();
stackPanel.AddToRoot();
stackPanel.Anchor(Anchor.Center);

var button1 = new Button();
stackPanel.AddChild(button1);

Styling.ActiveStyle.Colors.Primary = Color.Red;

var button2 = new Button();
stackPanel.AddChild(button2);

Styling.ActiveStyle.Colors.Primary = Color.Purple;

var button3 = new Button();
stackPanel.AddChild(button3);

This behavior may change in future versions of Gum.