> 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/3-parent-stacking-and-alignment.md).

# 3 - Parent, Stacking, and Alignment

## Introduction

Although it is technically possible to align UI manually by setting X and Y values, this type of layout makes it more difficult to maintain UI or create UI that is responsive to its parents.

Gum provides parent/children relationships which can be combined with layout values to easily center, stack, and dock instances.

A parent is an instance that contains other instances, called its children. When a parent moves, its children move with it. For more, see [Parent](https://docs.flatredball.com/gum/gum-tool/gum-elements/general-properties/parent.md).

### StackPanel Control

The key to creating layouts in Gum is to add your controls to containers. Containers can be used to create stacks, grids, add margins, and move children together. The StackPanel control is one of the most common controls since it automatically stacks its children, vertically by default or horizontally when its `Orientation` is changed.

This page starts with an empty MainScreen.

1. Select an instance in MainScreen, press `Delete`, and click **Yes** in the **Delete?** dialog. Repeat for each instance that was added on the previous pages.
2. Drag **StackPanel** from **Components** > **Controls** onto the Editor tab.

A StackPanelInstance now appears in MainScreen.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FZkI7tWyxmqmHOC9rgpvh%2F13_10_43_53.png?alt=media&amp;token=a71c9b48-f618-4b87-ac3f-b3cfaf9a3981" alt=""><figcaption><p>StackPanel in MainScreen</p></figcaption></figure>

To add buttons to the StackPanel:

1. Drag **ButtonStandard** from **Components** > **Controls** onto **StackPanelInstance** in the Project tab.
2. Select the new button, then press `CTRL+C` and `CTRL+V` to add another button. Repeat until the stack of buttons extends past the bottom of the StackPanelInstance's outline.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FciZc8cUINsbBqUrWEbT7%2F13_10_45_30.gif?alt=media&amp;token=0a913fe1-351d-46bf-a735-7856f768e5af" alt=""><figcaption><p>ButtonStandard instances added to a StackPanel</p></figcaption></figure>

The buttons stack top to bottom inside StackPanelInstance.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2F0r0fUsf756R1tm0kZ28d%2F13_10_58_39.png?alt=media&amp;token=cf0d0f7d-6dce-400c-b4d2-8e70adce688c" alt=""><figcaption><p>Buttons extending past the StackPanelInstance's outline</p></figcaption></figure>

### Alignment and Dock

The **Alignment** tab positions the selected instance. Its **Anchor** buttons change position only, and its **Dock** buttons change position and size.

To center the StackPanel:

1. Select **StackPanelInstance** and click the **Alignment** tab.
2. In the **Anchor** group, click the button in the middle of the grid.

The StackPanelInstance is now centered in MainScreen.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FD75Dfc2w4q4fvF9cPjM7%2Fimage.png?alt=media&amp;token=8cb23bfd-fb98-40be-8420-4da127f6c126" alt=""><figcaption><p>Centering the StackPanel</p></figcaption></figure>

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

By default the StackPanelInstance has an absolute width and height of 150, regardless of what it contains. This presents two problems. First, the contents of the stack panel are not perfectly center aligned - buttons are left-aligned and also spill out of the bottom. Second, buttons which spill out of the bottom of the StackPanel will not receive events.

To see the event problem:

1. Click the **Preview** button.
2. Move the mouse over the buttons.

The buttons inside the StackPanelInstance react to the mouse, while the buttons outside it do not.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FxpusgGj3E15xwLxWPzQH%2F13_11_16_10.gif?alt=media&amp;token=dac492a6-dab2-4d30-a9a3-a9652e9b168e" alt=""><figcaption><p>Button events in Gum</p></figcaption></figure>

Both problems can be solved by having the StackPanelInstance resize itself according to its children rather than using an absolute 150x150 size.

1. Select **StackPanelInstance** and click the **Alignment** tab.
2. In the **Dock** group, click the **Size to Children** button.

The StackPanelInstance now resizes to fit its buttons.

**Size to Children** sets the `Width Units` and `Height Units` of the StackPanelInstance to `Relative To Children`. For more on how values are measured, see [Width Units](https://docs.flatredball.com/gum/gum-tool/gum-elements/general-properties/width-units.md) and [Height Units](https://docs.flatredball.com/gum/gum-tool/gum-elements/general-properties/height-units.md).

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FutiGkgqrKQsymqOHZy3j%2F13_11_18_48.png?alt=media&amp;token=a97d26dc-2942-44a0-ba74-a26b54b9af77" alt=""><figcaption><p>Size to Children button in the Alignment tab</p></figcaption></figure>

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

### Spacing and Children Size

Now that the StackPanelInstance depends on its children's size, we can modify either the children or the spacing between the children and the stack panel updates automatically.

1. Select **StackPanelInstance** and click the **Variables** tab.
2. Change the `Spacing` variable.

The distance between each button changes.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FspDSUFAT7wxfD9LPupIE%2F13_11_23_39.gif?alt=media&amp;token=64bb5f2b-2c9a-4f22-a375-05766adbe91f" alt=""><figcaption><p>Spacing adjusts the distance between each button</p></figcaption></figure>

For more on spacing, see [Stack Spacing](https://docs.flatredball.com/gum/gum-tool/gum-elements/container/stack-spacing.md).

Similarly, changing the size of the buttons, by changing their `Height` or by adding text that wraps, updates the StackPanelInstance dynamically, and it stays centered.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FjUK76Wb5kADziMzR9siB%2F13_11_25_40.gif?alt=media&amp;token=f6f55b1a-a5db-496d-8328-3fc5fee550a1" alt=""><figcaption><p>The StackPanelInstance adjusting to changes in its buttons' size</p></figcaption></figure>

Individual button spacing can be adjusted by changing its `Y` value. The total spacing is the total of `Spacing` and `Y`.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2FLYell2iKz4JXhEb59g7u%2F13_11_27_05.png?alt=media&amp;token=ae436962-e2f7-4bdd-ad92-96bcad63a50e" alt=""><figcaption><p>A button's Y value adds to its spacing</p></figcaption></figure>

### Conclusion

This page shows how to work with parenting, stacking, and alignment, including the StackPanel, the Alignment tab, and spacing between children. The next tutorial introduces some of the most common control types.


---

# 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/3-parent-stacking-and-alignment.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.
