Adding and Removing Visual Children

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

Every control in Gum has a Visual property which defines its appearance and size. Some controls have simple Visuals, such as a single ContainerRuntime as the Visual for StackPanel. Other controls are made of multiple children, such as the Button containing a top-level ContainerRuntime with a NineSliceRuntime and TextRuntime.

This document shows how children can be added or removed from a control's Visuals to customize its appearance.

For information on working with standard visuals, see the Standard Visuals section.

Adding Children Visuals

Additional children can be added directly to a control's Visual (top visual), or as a child of existing children.

The following code shows how to add a colored rectangle to a Button.

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

var buttonVisual = (ButtonVisual)button.Visual;
var coloredRectangle = new ColoredRectangleRuntime();
buttonVisual.AddChild(coloredRectangle);
coloredRectangle.Color = Color.Red;
coloredRectangle.Anchor(Anchor.Left);
coloredRectangle.X = 8;
coloredRectangle.Width = 8;
coloredRectangle.Height = 8;

As mentioned above, new children can be added directly to the root, or they can be added as children of existing children. For example, the following code could be used to underline text on a Button:

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

var buttonVisual = (ButtonVisual)button.Visual;
var coloredRectangle = new ColoredRectangleRuntime();
buttonVisual.TextInstance.AddChild(coloredRectangle);
// So the text area doesn't fill the whole button:
buttonVisual.TextInstance.WidthUnits = Gum.DataTypes.DimensionUnitType.RelativeToChildren;
coloredRectangle.Color = Color.Red;
coloredRectangle.Dock(Dock.Bottom);
coloredRectangle.Height = 2;

Button with red underline under its text

Removing Children Visuals

Gum controls are very flexible and can function even if children are removed. Of course, removing children may limit the behavior of a control. For example, removing the TextInstance from a ButtonVisual results in the Button no longer displaying its Text string.

// Initialize
var button = new Button();
button.AddToRoot();
button.Anchor(Anchor.Center);
// if we remove the TextInstanc, we need to make sure the height of the button
// is absolute and no longer depends on its children:
button.Height = 32;
button.HeightUnits = Gum.DataTypes.DimensionUnitType.Absolute;

var buttonVisual = (ButtonVisual)button.Visual;
// setting Parent to null removes a child from its parent:
buttonVisual.TextInstance.Parent = null;

Button with its TextInstance removed

Of course, the TextIntance can also be made invisible, which results in similar behavior:

// Initialize
var button = new Button();
button.AddToRoot();
button.Anchor(Anchor.Center);
// if we remove the TextInstanc, we need to make sure the height of the button
// is absolute and no longer depends on its children:
button.Height = 32;
button.HeightUnits = Gum.DataTypes.DimensionUnitType.Absolute;

var buttonVisual = (ButtonVisual)button.Visual;
// setting Parent to null removes a child from its parent:
buttonVisual.TextInstance.Visible = false;

Replacing Children with Different Types

Default visual children can be replaced with children of different types to further customize controls. For example, the Button control uses a NineSlice for its background, but this can be replaced with other types such as ColoredRectangleRuntime or SpriteRuntime.

The following code shows how to replace a button's default background with a SpriteRuntime. For simplicity this button uses Lorem Picsum.

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

var buttonVisual = (ButtonVisual)button.Visual;
// setting Parent to null removes a child from its parent:
buttonVisual.Background.Parent = null;

var newBackground = new SpriteRuntime();
newBackground.SourceFileName = "https://picsum.photos/200/300";
// insert at 0 so it appears behind the text
buttonVisual.Children.Insert(0, newBackground);
// Size the button according to its new background:
button.Dock(Dock.SizeToChildren);

buttonVisual.ForegroundColor = Color.Black;

button.Click += (_, _) => button.Text = $"Clicked at {DateTime.Now}";

By removing the background, the highlighting behavior is no longer functional. This can be fixed by updating states. For more information, see the Styling Using States page.

Adding Backgrounds to Layout Containers

StackPanel and Grid do not include any visuals — they are invisible by default. To create a layout container with a visible background, wrap the StackPanel or Grid inside a Panel, then add a ColoredRectangleRuntime as a sibling of the StackPanel.

The following example creates a Panel with a dark background and a StackPanel containing buttons:

// Initialize
// Panel to hold both the background and the StackPanel
var panel = new Panel();
panel.AddToRoot();
panel.Anchor(Anchor.Center);
// Panel defaults to SizeToChildren, so set to Absolute for a fixed size
panel.WidthUnits = Gum.DataTypes.DimensionUnitType.Absolute;
panel.HeightUnits = Gum.DataTypes.DimensionUnitType.Absolute;
panel.Width = 240;
panel.Height = 300;

// Background fills the entire Panel
var background = new ColoredRectangleRuntime();
background.Dock(Gum.Wireframe.Dock.Fill);
background.Color = new Color(30, 30, 36);
panel.AddChild(background);

// StackPanel fills the Panel
var stack = new StackPanel();
stack.Dock(Gum.Wireframe.Dock.Fill);
stack.Spacing = 4;
panel.AddChild(stack);

for (int i = 0; i < 5; i++)
{
    var button = new Button();
    button.Text = "Button " + i;
    stack.AddChild(button);
}

Try on XnaFiddle.NET

To add padding between the background edge and the content, set a negative Width and Height on the StackPanel after docking. For example, stack.Width = -16 creates 8 pixels of padding on each side.

This same pattern applies to Grid — wrap it in a Panel with a ColoredRectangleRuntime to give it a visible background.

Do not add a ColoredRectangleRuntime as a background directly inside a StackPanel or Grid. In a stacking or grid layout, every child participates in the layout — a background rectangle would be treated as a stacked item rather than appearing behind the other children. ColoredRectangleRuntime can still be added as a regular child of a StackPanel (for example, as a divider or visual element), but it should not be used as a background inside a stacking container.