> 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/6-creating-custom-components.md).

# 6 - Creating Custom Components

## Introduction

This document covers how to create custom components. We'll be creating a component which can be used to display player stats and apply points earned by leveling up.

{% hint style="info" %}
This tutorial uses the default ButtonStandard. If you modified yours in previous tutorials it's okay - it should still work fine for this tutorial, but your screens and components may look a little different.
{% endhint %}

### Creating a New Component

New components can be created by right-clicking on the Components folder or any subfolder under Components.

For more on components, see [Component](https://docs.flatredball.com/gum/gum-tool/gum-elements/component.md).

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Ff0eAI4fhNkaNDSnH0KUb%2F13_16_52_44.png?alt=media&amp;token=0fac8091-02c5-4dbb-8799-2dbad25b8398" alt=""><figcaption><p>Add Component in the right-click menu</p></figcaption></figure>

Enter the name LevelUpItem as the name and click OK.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FQf5zjGtXXoIGAPhV03BQ%2F13_16_57_41.png?alt=media&amp;token=be420bba-909e-4842-a2d5-15b41e15e018" alt=""><figcaption><p>LevelUpItem in Gum</p></figcaption></figure>

### Adding Instances to LevelUpItem

The LevelUpItem will have 3 items:<br>

1. A Label for displaying the stat, such as Strength
2. A Label displaying the current value of the stat
3. A button that can be clicked to assign points

First we'll add the instances before we worry about their layout. Drag two Labels and a ButtonStandard from **Components** > **Controls** into LevelUpItem.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fwaxz04PJ80BhpuyF0bmr%2F13_17_19_46.png?alt=media&amp;token=94fbaedd-74ca-46a6-9579-b46814e3e855" alt=""><figcaption><p>LevelUpItem with a button and two labels</p></figcaption></figure>

Rather than leaving the default names, we can change the instances to something more expressive like StatName, StatValue, and AddPointButton.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2F1DCacjroAERnhKyGAL3s%2F14_05_15_38.png?alt=media&amp;token=3ff5c1fd-af45-4725-8922-614b95d2a1a9" alt=""><figcaption><p>LevelupItem with newly named instances</p></figcaption></figure>

### Adjusting Layout and Defaults

Next we'll adjust the layout of our control and its children.

First, set the values on the LevelUpItem itself by setting its:

* Width to `250`
* Height to `26`

Next, click on each of the instances and dock them as follows:

* AddPointButton: Dock Right
* StatName: Dock Left
* StatValue: Dock Right

Finally we can adjust the values for the instances:

* AddPointButton Text to `+`
* AddPointButton Width to `26`
* StatValue X to `-30` so it doesn't overlap the button
* StatValue Text to `999` as a default value
* StatName Text to `<Stat Name>`

We now have a LevelUpItem with a good setup and defaults.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FZd1ONHuJD7adG4IPJYbt%2F14_05_22_59.png?alt=media&amp;token=7712c06e-45b8-4885-ba0f-f9246a445152" alt=""><figcaption><p>LevelUpItem with its default layout and values</p></figcaption></figure>

### Exposed Variables

Next we'll set up exposed variables so that each instance can be independently modified. Before we create this, let's explore why exposed variables are needed.

To understand the need, we can create a screen with 2 LevelUpItem instances. These 2 instances can differ by setting their "top level" variables. In other words, we can change their positions, sizes, and visibility. However, we cannot change the `<Stat Name>` or `999` values. Those are properties that belong to the Text instances contained within each LevelUpItem.

This is intentional - if it didn't work this way, then the LevelUpItem would expose every property of every contained item, which would be an overwhelming number of variables to deal with. Instead, variables that belong to instances in a component are *hidden* unless explicitly exposed.

We can solve this by picking which variables we want to expose so that they can be set per LevelUpItem instance.

First, we'll expose the variable to replace `<Stat Name>` . To do this:

1. Select the StatName instance inside LevelUpItem
2. Right-click on the Text variable
3. Select Expose Variable<br>

   <figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FEVhf0sXZP8FnskwjAbks%2F14_05_38_20.png?alt=media&amp;token=09a45003-91d5-4630-88a6-0665b4a6fe87" alt=""><figcaption><p>Expose Variable right click item</p></figcaption></figure>
4. Enter the desired name, such as `Stat` . Notice that you cannot have an exposed variable that matches the name of your instance, so StatName is an invalid variable name.

Repeat this by exposing the `Text` variable on StatValue, creating a variable named `Value` . Also, repeat this by exposing the AddPointButton's `Visible` variable, naming it `IsAddPointVisible` .

After you're finished, these variables should show up if you select the LevelUpItem component.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FVI05ujXv94AFHkIEEzjA%2F14_05_41_58.png?alt=media&amp;token=43171d85-8701-4e85-a45d-c919da613f2c" alt=""><figcaption><p>Exposed variables shown on the component</p></figcaption></figure>

Now that we have these exposed variables, we can also customize them per-instance in a screen.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FcMJPDWIVsLLaEw7uNliO%2F14_05_43_20.png?alt=media&amp;token=898af86d-2db6-46ce-9870-278b9b33b260" alt=""><figcaption><p>Two LevelUpItem instances with different exposed variable values</p></figcaption></figure>

For more, see [Exposed Variables](https://docs.flatredball.com/gum/gum-tool/gum-elements/component/exposed-variables.md).

### Hiding Variables

Gum also supports hiding variables at the component level. Hiding variables makes it easier to work with component instances by only displaying variables which should be modified for each instance.

For more on hiding variables, see [Hide from Instances](https://docs.flatredball.com/gum/gum-tool/variables/hide-from-instances.md).

For example, some variables may not make much sense to expose, such as the Children Layout variable on a LevelUpItem. After all, we have determined a very specific layout of our children, and we don't want each instance to change this.

Similarly, some properties might just be considered noise that we can remove, such as `Rotation` and `Flip Horizontal` - these are variables which may be useful in some situations, but we may decide that our game never needs them.

We can right-click on any variable in the LevelUpItem to hide it.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FFY17Ps14GCmNGZUy9bja%2F14_05_47_13.png?alt=media&amp;token=86cf7f65-3811-476b-930a-642d1c24bef4" alt=""><figcaption><p>Hide from Instances right-click item</p></figcaption></figure>

By removing all of the variables that we never intend to change, we can make it much easier to work with a LevelUpItem instance.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FtZfXxv7sPJWfYJIpFcTt%2F14_05_49_19.png?alt=media&amp;token=a76e2961-de2b-4e36-9521-93869b9206a6" alt=""><figcaption><p>LevelUpItemInstance only displaying some variables - other variables have been hidden</p></figcaption></figure>

Note that hiding a variable from instances does not hide it at the component level - all variables are still available there and can still be given defaults that all instances use.

Hidden variables are also labeled as hidden with a small label under each variable.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FzuRFxgSn7kfDe0saOp4x%2F14_05_50_45.png?alt=media&amp;token=2b26e3e8-d920-4258-8aba-9ce5af4fe90e" alt=""><figcaption><p>Hidden Variables on a component display a label</p></figcaption></figure>

### Conclusion

This tutorial shows how to create a simple component with explicitly exposed variables along with hidden variables. This covers the concepts of creating a component, but components can be anything that you might want to encapsulate or reuse. It's best to spend some time creating new components or modifying the LevelUpItem component that we created to become more familiar with how components work.

To use the screens and components you create in a game, continue with the [Gum UI Tool and Code Tutorial](https://docs.flatredball.com/gum/code/getting-started/tutorials/gum-project-forms-tutorial.md).

For more on working in the Gum tool, see [Gum Elements](https://docs.flatredball.com/gum/gum-tool/gum-elements.md), [Variables](https://docs.flatredball.com/gum/gum-tool/variables.md), and [States](https://docs.flatredball.com/gum/gum-tool/gum-elements/states.md).

If you have questions, or want to show what you are building, join the [Discord chat](https://discord.gg/EvqwmSQuBz).


---

# 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/6-creating-custom-components.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.
