> 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/gum-tool/tutorials-and-examples/working-with-gum/5-customizing-control-appearance.md).

# 5 - Customizing Control Appearance

## Introduction

The controls in a default project act as a starting point for customization. These can be fully customized. Note that the available customizations depend on the theme you selected when creating your project.

This page discusses customizing the Standard theme, but if you are using a different theme then the customization steps will be slightly different.

### Component States

A state is a collection of variables that represents a configuration of a component, and a category organizes similar states into one group.

Many Gum components have multiple states to control their appearance in response to cursor, keyboard, focus, or enabled actions/states. For example, the ButtonStandard component has a number of states under ButtonCategory.

For more on states and categories, see [States](https://docs.flatredball.com/gum/gum-tool/gum-elements/states.md) and [Categories](https://docs.flatredball.com/gum/gum-tool/gum-elements/states/categories.md).

You can click each of the states to see how it looks.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FSQNwjMTNg1LeJggYncUW%2F13_14_22_59.png?alt=media&amp;token=1283912a-e9f8-4255-8b71-7c7e4c313ac2" alt=""><figcaption><p>ButtonStandard in a Disabled state</p></figcaption></figure>

Each state can set any variable on any instance. To see which variables are set by the ButtonCategory, click on ButtonCategory.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FRHSC6567Idlv8EzRGVTm%2F13_14_26_05.png?alt=media&amp;token=7d52bb6c-3e78-4b27-ac69-26419e232151" alt=""><figcaption><p>Variables set by ButtonCategory</p></figcaption></figure>

This tells us that when the state of a button changes, the background color, text color, and focused indicator visibility are changed.

Even once we select a state like Enabled, the color value itself is read only. This is because the ButtonStandard is set to use a centralized color value, rather than explicitly setting a color value. For example, the background is set to use the Primary color in our Styles component.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Ff3anUGCJsP7DQWtlMXOb%2F13_14_34_03.png?alt=media&amp;token=33a154cb-a00b-45e5-bbee-d937ea800e28" alt=""><figcaption><p>The Enabled state sets Color from Styles.Primary</p></figcaption></figure>

If we want to change the color, we can do a few things:

1. Change the color in the Styles component by selecting the instance (like Primary) in the Styles component and changing its color.
2. Change which style color is being referenced.
3. Remove the styles reference altogether and set the color directly.
4. Replace the visuals completely

Let's look at how to perform each of these.

### 1 - Changing the Styles component (Global Change)

To change colors globally, select the Styles component and find the color that you would like to change under Colors, such as Primary. Keep in mind that these colors may be used by many controls, so a change here can affect many controls and states.

These changes can be made while Gum Preview is open, so changes can be seen in real time. Pinning the DemoScreenGum in Gum Preview is a great way to see how these changes affect your project.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FFXjCGLkeSp2ssEohELZa%2F13_14_51_51.gif?alt=media&amp;token=8e784a8f-7b91-4a28-9d18-2abf97787691" alt=""><figcaption><p>Changing a Styles color while Gum Preview is open</p></figcaption></figure>

Each style has its own set of colors, and these colors affect different components and states in their own way, so you may need to spend some time looking at the variables on different states and test the values in Gum Preview.

### 2 - Changing Style References

Styles components come with a set of style colors built-in, and any of these can be used by your component states.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2F3feU1y1WDqFvLvjim1Uo%2F13_14_56_15.png?alt=media&amp;token=1f1e7f6b-4749-4e64-ade3-f0c0a2ce69e4" alt=""><figcaption><p>Colors in the Styles component</p></figcaption></figure>

The colors that are used are set in variable references on component instances. For example, the background color for ButtonStandard is set in each of its states. To see the variable references, select the state, select the instance, and scroll to the bottom of the Variables tab to see the variable references.

For more on variable references, see [Variable References](https://docs.flatredball.com/gum/gum-tool/gum-elements/general-properties/variable-references.md).

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FxzlZ0gQIXlI8GJBB445o%2Fimage.png?alt=media&amp;token=f1d561f9-5d5a-4517-be0a-b4bab7983b23" alt=""><figcaption><p>Variable reference on a component's instance</p></figcaption></figure>

This can be edited to use a different color, such as changing from Primary to Warning.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FxYADgOnPWiqUTY7iXNiQ%2F13_14_58_57.png?alt=media&amp;token=681abb49-af30-4921-9e2e-16e644742e85" alt=""><figcaption><p>Variable reference using Warning</p></figcaption></figure>

You're not limited to the existing style colors either. You are free to add new colors to the Styles component beyond the existing colors.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FCTYBrY6YUqhaDSVObvGd%2F13_15_00_55.png?alt=media&amp;token=4c9e0451-e430-4c15-bd8f-8cc8f6c89626" alt=""><figcaption><p>Custom Color in Styles</p></figcaption></figure>

Once this is added, it can be referenced on any state in any component.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2F9LP1dNBhz6sJOmrW9cNJ%2F13_15_02_20.png?alt=media&amp;token=8a1d481d-23b5-4964-9090-2ddf79a19c0a" alt=""><figcaption><p>CheckBox using a new custom color</p></figcaption></figure>

### 3 - Removing Style Color References

Style colors provide a central location for global colors, but they also add complexity to your project. If you would rather not use centralized colors, you can completely remove references altogether.

For example, to remove a style color on the TextBox's background:

1. Select the TextBox's background
2. Select the desired state
3. Scroll down to the Color value
4. Press the icon for removing variable references

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FcY4FXwluySMwjAIlCt50%2F13_15_17_42.png?alt=media&amp;token=d3064216-591e-4677-8fa2-1d5efdc2a966" alt=""><figcaption><p>Removing variable references for the Enabled state on the TextBox background</p></figcaption></figure>

Once this reference is removed, the color can be set directly.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2For634KJg6UKjjnGW66GS%2F13_15_18_33.png?alt=media&amp;token=6fb28dd6-f0cc-42bd-8edc-d7d7b830c87b" alt=""><figcaption><p>Direct color assignment after removing reference</p></figcaption></figure>

### 4 - Replacing Visuals Completely

Visuals in components can be completely removed or replaced to customize the appearance of a component. When components are replaced, the newly-added instances in a component do not have any built-in functionality. The individual states must be set up manually (shown below).

As an example, we will replace the background of the ButtonStandard to use a rounded Rectangle rather than a NineSlice.

For more on Rectangle, see [Rectangle](https://docs.flatredball.com/gum/gum-tool/gum-elements/rectangle.md) and [Is Filled](https://docs.flatredball.com/gum/gum-tool/gum-elements/shape-properties/is-filled.md).

First, select and delete the background on ButtonStandard.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2F3kI3r2En4eecq9Lano2f%2F13_15_36_57.png?alt=media&amp;token=fe79c307-cd10-4496-b8a5-1ac65c21c994" alt=""><figcaption><p>ButtonStandard after deleting its background</p></figcaption></figure>

Next we'll add a Rectangle as a new background. To do this:

1. Drag+drop a Rectangle onto ButtonStandard
2. Drag the new RectangleInstance to place it first in the list. Items first in the list are drawn behind items last in the list.
3. Click the Alignment tab, then click **Fill** in the **Dock** group

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FRC0NahY0Z2FxIqBsSZg4%2F13_15_46_24.gif?alt=media&amp;token=f3cb98c6-3658-48a8-9450-81a23feb37c2" alt=""><figcaption><p>Adding a Rectangle to ButtonStandard</p></figcaption></figure>

For more on draw order, see [Order](https://docs.flatredball.com/gum/gum-tool/gum-elements/general-properties/order.md).

Now the rectangle can be customized to match the style you want for your button. For example, we can set:

* Is Filled - checked (true)
* Fill Color 0000FF (blue)
* Corner Radius 8

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FNCt1tgk5SSoku8aqQfLA%2F13_15_48_10.png?alt=media&amp;token=91903068-b683-41ec-a24d-fdbef33dc38f" alt=""><figcaption><p>Button with blue fill</p></figcaption></figure>

As mentioned before, since we deleted the background earlier, we need to re-wire the categories. We can do this by selecting different states in ButtonCategory and changing any value on our newly-created background.

For example, we can set the Fill Color in the Pushed state to a darker blue color.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FH5efxy0mZ7z9GT30Y2xq%2F13_15_51_11.png?alt=media&amp;token=cc3354b1-8ac2-4fe1-98b2-d89a6622bb75" alt=""><figcaption><p>Darker color on Pushed state</p></figcaption></figure>

Now the button should react to push state.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FbryGRGXJUf80ILP0M7N6%2F13_15_52_10.gif?alt=media&amp;token=96b11537-4260-4aee-9fc3-9bb6f4e8e24b" alt=""><figcaption><p>Pushed state in preview</p></figcaption></figure>

### Conclusion

This page shows how to customize the appearance of components. The next page shows how to create brand new components.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flatredball.com/gum/gum-tool/tutorials-and-examples/working-with-gum/5-customizing-control-appearance.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
