> 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/4-control-types.md).

# 4 - Control Types

## Introduction

By default Gum projects include typical controls for game UI including Button, CheckBox, TextBox, and ListBox. This page covers some of the most common types of controls and explains how to work with them. This page does not provide exhaustive coverage of all controls, so you are encouraged to explore and try them out in your own project.

Controls are added to your Controls folder under Components. Note that if you used a different theme, the folder names may differ, but most of the controls will be the same.

Label and CheckBox, which are used later in this series, are in the same folder.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FBoWFoaFDspHIcPchUL8C%2F13_12_48_44.png?alt=media&amp;token=ca78fe7f-d2f1-42d0-8e43-ae62bc65e798" alt=""><figcaption><p>Controls in the Project tab</p></figcaption></figure>

### Button

The ButtonStandard control is one of the most common controls. It reacts to the cursor hovering over it and clicking it.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FepCvhAN5TSNA74QxILTa%2F13_12_58_49.png?alt=media&amp;token=5cc5f908-7432-4c9d-8bbf-69550b1585f3" alt=""><figcaption><p>ButtonStandard Component</p></figcaption></figure>

By default Buttons contain text that line wraps, and the height of a button is relative to its text. Adding additional text makes it wrap onto more lines, which grows the size of the button.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FZTAaOY4lj5TCVD7ricyK%2F13_13_06_04.png?alt=media&amp;token=fb018623-a752-4be9-8af0-ce7b4754a4ba" alt=""><figcaption><p>Buttons with different text</p></figcaption></figure>

Buttons can also be disabled, which changes their appearance and makes them not respond to hover or click events.

1. Select the button instance.
2. In the **Behavior** category of the Variables tab, clear **Is Enabled**.

The button changes to its disabled appearance.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FsNi81K34huhbamPgPw8m%2F13_13_07_18.png?alt=media&amp;token=988fa0de-eae0-4643-b05f-c257898ad77d" alt=""><figcaption><p>Enabled and Disabled button</p></figcaption></figure>

### TextBox

Gum provides a fully-functional TextBox component which accepts typing, selection, copy/paste, and multi-line editing.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FIyQrF8zjbt9r3YCUVy6V%2F13_13_11_59.png?alt=media&amp;token=dda39751-a8d0-4a1c-9b15-54b9589d3c45" alt=""><figcaption><p>TextBox in Gum</p></figcaption></figure>

TextBox-specific variables are all organized under the Behavior category. TextBox has far more variables controlling its behavior compared to Button.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FhElsQRQ0HCSsvM2mNhWI%2F13_13_13_19.png?alt=media&amp;token=65dfdc26-bf69-484b-94df-9ce08cbec2a6" alt=""><figcaption><p>TextBox variables in the Behavior category</p></figcaption></figure>

#### Multi-line TextBox

TextBoxes use a combination of variables to support multi-line editing.

The Text Wrapping variable controls whether text wraps or stays on one line. To see multi-line text easily, you may also want to adjust a TextBox's Height.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fsvz1bZCBfFpGjhFhfop8%2F13_13_15_53.png?alt=media&amp;token=f2babff7-4242-4a0d-955f-5b6c0866ab56" alt=""><figcaption><p>TextBox with text wrapping</p></figcaption></figure>

You can test this behavior using Gum Preview.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FRjWFKzbp4aHqWsbBWAtU%2F13_13_17_17.gif?alt=media&amp;token=5c1206b5-3976-4cc4-a5c8-e9700fad6bf2" alt=""><figcaption><p>TextBox with wrapping</p></figcaption></figure>

If Accepts Return is checked, then pressing the Enter/Return key inserts a new line.

### ListBox

ListBoxes can contain any number of ListBoxItem instances. These can be single or multi-selected. If enough items are displayed, a scroll bar appears when a game runs.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FLedLl1czhQi8f5hBnlyn%2F13_13_21_50.png?alt=media&amp;token=1ccbdd81-c5ad-4142-bf0b-0b209d439785" alt=""><figcaption><p>ListBox in Gum</p></figcaption></figure>

ListBoxItem instances can be added in the tool or in game. Most of the time ListBoxes are populated in game, but Gum does support adding ListBoxItems manually.

To add items to a ListBox, drag+drop ListBoxItem instances onto the ListBox.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FuzqvMTiZs1QGsW9wxEeE%2F13_13_22_48.gif?alt=media&amp;token=13ce9de2-1674-4694-8e0a-11cf29e613d3" alt=""><figcaption><p>Adding items to ListBox</p></figcaption></figure>

Each item's text can be set by selecting it and changing its `List Item Display Text` variable.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FMcmy9WaGNXkw9gKWwP4Q%2F13_13_29_23.png?alt=media&amp;token=deb97843-a49a-4c64-b9a8-2391a20fe5d1" alt=""><figcaption><p>ListBoxItem with changed text</p></figcaption></figure>

If enough items are added, then the ListBox displays a scroll bar in game.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FpmpJ6qq5Ph9C9oEvNVmj%2F13_13_30_18.png?alt=media&amp;token=5d91789c-aff0-4590-8b19-5274f62d4457" alt=""><figcaption><p>ListBox with a scroll bar</p></figcaption></figure>

### Conclusion

This page shows how to work with some of the most common controls. As mentioned earlier, Gum has lots of controls so you'll want to try out some of the other controls in your screen and in the Preview window to get a feel for what is available.

The next tutorial discusses how to customize control appearance.


---

# 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/4-control-types.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.
