> 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/gum-elements/container/children-layout.md). # Children Layout ## Introduction **`Children Layout`** determines how a container positions its children. The default value is `Regular` which means that children are positioned according to their [X Units](/gum/gum-tool/gum-elements/general-properties/x-units.md) and [Y Units](/gum/gum-tool/gum-elements/general-properties/y-units.md).

`Top to Bottom Stack` results in the children stacking one on top of another, from top to bottom. `Left to Right Stack` results in the children stacking one beside another, from left to right. `Auto Grid Horizontal` results in the children being placed in a grid, filling in horizontally first before wrapping to the next row. `Auto Grid Vertical` results in the children being placed in a grid, filling in vertically first before wrapping to a new column. ## Example The following animation shows how to use the `ChildrenLayout` variable to change the default position of a Container's children:

Changing Children Layout updates the position of all contained children

## Regular `Regular` layout positions each child independent of every other child. The position of one child does not affect the position other children. This is the default layout for containers.

Two ColoredRectangles using Regular layout

## Top to Bottom Stack `Top to Bottom Stack` results in each child being positioned after its previous sibling vertically. This can be used to create horizontal stacks.

`Top to Bottom Stack` behaves similarly to `Left to Right Stack`. For a detailed discussion see the `Left to Right Stack` section below. ## Left to Right Stack `Left to Right Stack` results in each child being positioned after its previous sibling horizontally. This can be used to create vertical stacks.

### Stacking and Container Height Units and Width Units A container can stack its children and also have its size based on its children. This results in the container growing as children are added. For example, the following shows a container with its `Height Units` set to `Relative To Children` and its `Children Layout` set to **Top To Bottom Stack**. As more children are added the container grows vertically.

Top To Bottom Stack can be used with Height Units of Relative To Children to grow the container as children are added

If the container also has a `Max Height` (or a `Max Width` in a `Left to Right Stack`), it grows until it reaches that value. A child that crosses the max stays in the stack and extends past the container's edge. If `Wraps Children` is checked, that child moves to a new column (or row) instead, so the container stops at the last child that fits. For more information see the [Wraps Children](/gum/gum-tool/gum-elements/container/wraps-children.md) page. {% hint style="warning" %} **Breaking change in November 2026:** Before this version, a stack without `Wraps Children` stopped growing at the last child that fit under its max, the same as a wrapping stack, so it could end up smaller than its max. Available in November 2026, or now if building Gum from source. For more information see [Migrating to 2026 November](/gum/gum-tool/upgrading/migrating-to-2026-november.md). {% endhint %} Invisible children are ignored in the stack, so toggling the Visible property removes a child from the stack.

Visible set to false removes an item from stacking

### Stacking and X/Y Values When children stack, each child's X or Y depends on the boundary of its previous sibling. When stacking vertically, the child's Y value begins at the bottom side of the previous item. Similarly, when stacking horizontally, the child's X value begins at the right side of the previous item. For example, the following image shows a Text object with a Y value of 20. Notice that it is positioned 20 units below the item above it.

A Text's Y value can be used to separate it from its previous sibling in a Top to Bottom Stack

This effect is easy to notice when dragging an object inside a stack, as shown in the following animation:

As a Y value changes, all following siblings move too

### Stacking and Units If instances are stacked in a container, the stacking controls the instance values based on the direction of the stack. * `Top to Bottom Stack` containers control the Y value of their children. * `Left to Right Stack` containers control the X value of their children. The position value which is not controlled by the stack can be changed freely without any impact on the stacking. The first child in a stack uses its units and origin on the stacking axis like any other child. Every child after the first ignores them, so the stack always places it right after its previous sibling: * In a `Top to Bottom Stack`, later children measure `Y` from the bottom of the previous sibling whatever their `Y Units`, and treat `Y Origin` as `Top`. * In a `Left to Right Stack`, later children measure `X` from the right side of the previous sibling whatever their `X Units`, and treat `X Origin` as `Left`. The child's `X` or `Y` value still applies, and adds space between the child and its previous sibling. For more information see the [Stacking and Children Origin](#stacking-and-children-origin) section below. For example, if a container stacks its children using a `Top to Bottom Stack`, the children in the stack are free to change their X values. The following animation shows how children can be left, center, or right anchored (which changes their `X Units` and `X Origin`) without affecting the other children in the stack.

Changing horizontal layout values does not affect siblings in a Top to Bottom Stack

### Stack Spacing `Top to Bottom Stack` and `Left to Right Stack` separate their children using the `Stack Spacing` value. For more information, see the [Stack Spacing](/gum/gum-tool/gum-elements/container/stack-spacing.md) page. ### Stacking and Children Origin The position of a child in a stack is determined by the size of the previous item in the stack. Consider a container with a blue rectangle which stacks horizontally. The blue occupies some space according to its absolute width. The next instance after the blue rectangle is placed relative to the right side of the blue rectangle.

The next item's position is based on the right side of the blue rectangle

For example, if a red rectangle (partially transparent to make it easier to see when overlapping) is added to the container, the stack creates a layout similar to the following image: ![Red rectangle is positioned relative to the right side of the blue rectangle.](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-c8cf36fc10342d0a25f8a7c47f64e7639208756c%2F03_05%2028%2005.png?alt=media) The red rectangle stays in this position even if its [X Origin](/gum/gum-tool/gum-elements/general-properties/x-origin.md) is `Center` or `Right`. A child after the first ignores its origin on the stacking axis, so it never overlaps its previous sibling. Its origin on the other axis works normally, so a child in a `Top to Bottom Stack` can still center itself horizontally. The first child in a stack uses its origin on both axes. {% hint style="warning" %} **Breaking change in November 2026:** Before this version, a later child's `X Origin` (in a `Left to Right Stack`) or `Y Origin` (in a `Top to Bottom Stack`) moved it back over its previous sibling. A `Center` origin overlapped the previous sibling by half the child's size, and a `Right` or `Bottom` origin overlapped it completely. Available in November 2026, or now if building Gum from source. For more information see [Migrating to 2026 November](/gum/gum-tool/upgrading/migrating-to-2026-november.md). {% endhint %} ### Stacking and Rotation A stack places the next child after a rotated child as if the rotated child were not rotated. With the default `Top` and `Left` origin, a rotated child turns about its top-left corner, so it can overlap its neighbors or leave gaps. With another origin, such as `Center`, the rotation also shifts where the next child starts. A rotated child in an `Auto Grid Horizontal` or `Auto Grid Vertical` container turns within its own cell and never moves the other cells. {% hint style="warning" %} Stacking with rotation may become more sophisticated in a future version of Gum, so this behavior may change. {% endhint %} ### Wraps Children The [Wraps Children](/gum/gum-tool/gum-elements/container/wraps-children.md) property controls how stacking behaves beyond boundaries. For more information, see the [Wraps Children](/gum/gum-tool/gum-elements/container/wraps-children.md) page. In a wrapping stack, each row or column is the parent of its children on the other axis for positioning, so a centered child centers in its row. For more information see [Positioning Children Within a Row or Column](/gum/gum-tool/gum-elements/container/wraps-children.md#positioning-children-within-a-row-or-column). ### Reordering Children Children of a container which uses the `Top To Bottom Stack` or `Left To Right Stack` are ordered according to their order in the tree view on the left. By default this is the order in which the children are added to a parent container.

Item order in the Project tab determines the order of items in a stacked container

Children can be reordered using the right-click menu on an instance. ![](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-ac78604b91f626423a68fd6327adcd19ac9f9805%2FReorderStackedChildren%20\(1\).gif?alt=media) Alternatively, children order can be changed by clicking on the item in the tree view, holding down the ALT key, then pressing the up or down arrows.

For more information on ordering, see the [Order](/gum/gum-tool/gum-elements/general-properties/order.md) page. ## Auto Grid Horizontal and Auto Grid Vertical `Auto Grid Horizontal` and `Auto Grid Vertical` layouts result in each child of the container being placed in its own cell. All position and size values are relative to the entire cell, so children can expand to fill their cell or be positioned according to any side or corner. The following image shows a container with 4x4 auto grid. Each child is positioned relative to the top-left corner of each grid. In this case, each child has an `Absolute` `Width` and `Height` of `50` and the parent container is sized `256x256`. This results in each rectangle leaving a gap between itself and its neighbor.

Blue ColoredRectangles in a Container using Children Layout of Auto Grid Horizontal

The following shows a container with an `Auto Grid Horizontal` and `Vertical Cells` of 2, resulting in a 2x2 grid. As children are added to the container through copy/paste, each child is placed in its own cell.

Container using Auto Grid Horizontal creating a 2x2 grid

The number of cells is controlled by the `Auto Grid Horizontal Cells` and `Auto Grid Vertical Cells`. Increasing the number of cells results in the rows or columns adjusting automatically.

Increasing Auto Grid Horizontal Cells adds additional columns

Each child occupies one cell, and the order of the children controls the order of the placement in grids. The first child occupies the top-left row. If using `Auto Grid Horizontal`, each child is placed to the right of its preceding sibling, wrapping to the next line when reaching the end of a row. If using `Auto Grid Vertical`, each child is placed below its preceding sibling, wrapping to the next column when reaching the end of a column.

Auto Grid Vertical and Horizontal change the ordering of children

Children can be reordered by using the alt+arrow key in the tree view, resulting in reordering just like when using a stacking `Children Layout`.

Alt+arrow changes the order of the selected item in the tree view, updating the positions in the grid

Children treat their particular cell in the grid as their parent, so any sizes or positions will be based on their parent cell. In other words, if a child's `Width Units` is set to `Relative To Parent`, the parent in this case is the cell, not the entire Container instance.

Changing Anchor and Dock values results in children being placed relative to their particular cell

The number of cells in a grid is determined by multiplying `Auto Grid Cells Horizontal` by `Auto Grid Cells Vertical`. If a container has more children than its total cells and if the container's size does not depend on its children, additional children spill over the bounds of the grid. The following animation shows a 3x3 grid using `Auto Grid Horizontal`. As more children are added, additional rows are added below the bounds of the grid.

Additional children can create rows or columns outside of the bounds of the grid.

If the container has its `Width Units` or `Height Units` set to `Relative To Children`, then its size may adjust in response to adding more children. For more information, see the [Width Units](/gum/gum-tool/gum-elements/general-properties/width-units.md#relative-to-children-and-auto-grid-horizontal) and [Height Units](/gum/gum-tool/gum-elements/general-properties/height-units.md#relative-to-children-and-auto-grid-vertical) pages. When using `Auto Grid Horizontal`, the number of columns is fixed, but additional rows can be added beyond the bounds of the container. When using `Auto Grid Vertical`, the number of rows is fixed, but additional columns can be added beyond the bounds of the container. ### Stack Spacing {% hint style="info" %} Stack Spacing was added to Auto Grid in the January 2026 version of the Gum tool. {% endhint %} `Stack Spacing` can be used to separate cells in a grid. This is most commonly used when the grid's children use `Width Units` or `Height Units` of `Relative to Parent`. The following shows a grid with children which fill their cells. Changing the `Stack Spacing` adds gaps between each child.

### Auto Grid and Width/Height Units If a container's `Children Layout` is set to `Auto Grid Horizontal` or `Auto Grid Vertical`, it can size itself according to the largest cell by using `Width Units` or `Height Units` of `Relative To Children`. For more information see the [Width Units](/gum/gum-tool/gum-elements/general-properties/width-units.md#relative-to-children-and-auto-grid-horizontal) and [Height Units](/gum/gum-tool/gum-elements/general-properties/height-units.md#relative-to-children-and-auto-grid-vertical) pages. --- # 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/gum-elements/container/children-layout.md?ask=&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.