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:

// Initialize
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);

    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);

    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 Fonts

Just as Styling.ActiveStyle.Colors controls the colors of every control created after it is set, Styling.ActiveStyle.Text controls their fonts — so a single assignment restyles text across the entire project without modifying individual controls. It exposes three text states:

• Normal — the default font, applied to the text of most controls (Button, Label, TextBox, ListBoxItem, and so on).
• Strong — a bold variant, applied by ComboBox.
• Emphasis — an italic variant (not applied by the built-in controls; available when you apply it to your own text).

Set the Font, FontSize, IsBold, or IsItalic values on a state to change it. The following code relies on KernSmith for dynamic font creation. For more information on dynamic fonts and information on using KernSmith, see the Font Strategies page.

// initialize
GumUI.Initialize(this);

CustomSetPropertyOnRenderable.InMemoryFontCreator =
    new KernSmithFontCreator(GraphicsDevice);

var textStyling = Gum.Forms.DefaultVisuals.V3.Styling.ActiveStyle.Text;
var normalState = textStyling.Normal;
normalState.SetValue("Font", "Consolas", "string");
normalState.SetValue("FontSize", 28, "int");

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

base.Initialize();

Button using larger Consolas font

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:

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