# Stack

<figure><img src="/files/BqeKkhJ9GBViL81fTB4y" alt="A hero image illustrating the Stack widget with multiple layers, like an image with text and an icon on top."><figcaption><p>The Stack widget is essential for creating complex, layered user interfaces.</p></figcaption></figure>

The **Stack** widget is a powerful layout widget that allows you to place widgets on top of each other, creating layered and overlapping UIs. It arranges its children in a back-to-front order, with the first child being at the bottom and the last child at the top.

{% embed url="<https://www.youtube.com/watch?v=nG6iYEcuSJs>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=nG6iYEcuSJs>

#### Adding a Stack Widget

The Stack widget is located in the **Layout Elements** section of the Widget Palette. Once added, you can add child widgets to it and configure its properties from the **Widget Properties Panel**.

### Core Concept: Layering and Positioning

The primary purpose of a Stack is to layer widgets along the Z-axis (depth). Children of a Stack can be either **non-positioned** or **positioned**, which determines how they are placed.

* **Stacking Order**: Children are painted in the order they appear in the `children` list. The first widget is at the bottom, and subsequent widgets are painted on top of it.
* **Non-Positioned Children**: By default, a child is non-positioned. Its alignment is controlled by the parent Stack's `Alignment` property, and its size is determined by the `Fit` property.
* **Positioned Children**: A child becomes "positioned" when you set one or more of its position properties (`top`, `bottom`, `left`, `right`) in the **Children Position** section of the Stack's properties. This gives you precise control over its location and size relative to the Stack's boundaries, overriding the Stack's `Alignment` and `Fit` for that specific child.

<figure><img src="/files/mHvtpsmK0lALolwsT755" alt=""><figcaption><p>The Stack widget enables complex, layered user interfaces.</p></figcaption></figure>

***

### Properties

#### Stack Properties

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Alignment</code></td><td>Controls the alignment of all <strong>non-positioned</strong> children within the Stack's bounds. The default is <code>TopStart</code> (top-left corner).</td></tr><tr><td><code>Fit</code></td><td>Determines how to size the <strong>non-positioned</strong> children. Options are: <code>Loose</code> (children can be smaller than the Stack), <code>Expand</code> (children are forced to be as big as the Stack), and <code>Passthrough</code> (children's constraints are passed through from the Stack's parent).</td></tr><tr><td><code>Clip Behavior</code></td><td>Defines whether children are allowed to paint outside the Stack's boundaries. Options include <code>HardEdge</code> (content is clipped), and <code>None</code> (content is not clipped).</td></tr></tbody></table>

***

### Positioning Children

The key to creating precisely arranged layouts within a Stack is the **Children Position** section in the widget's property panel. This section lists all direct children, allowing you to set a `Position` for each one by defining the properties below.

#### Position Properties

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Top</code></td><td>The distance to offset the child from the top edge of the Stack.</td></tr><tr><td><code>Bottom</code></td><td>The distance to offset the child from the bottom edge of the Stack.</td></tr><tr><td><code>Left</code></td><td>The distance to offset the child from the left edge of the Stack.</td></tr><tr><td><code>Right</code></td><td>The distance to offset the child from the right edge of the Stack.</td></tr></tbody></table>

#### Positioning Behaviors

By combining the position properties, you can achieve several distinct layout behaviors.

<table><thead><tr><th width="200">Behavior</th><th width="250">Properties Set</th><th>Description &#x26; Use Case</th></tr></thead><tbody><tr><td><strong>Non-Positioned</strong></td><td>None (<code>top</code>, <code>left</code>, <code>right</code>, <code>bottom</code> are all unset).</td><td>The child's position is determined by the parent Stack's <code>Alignment</code> property. The child retains its natural size, unless the Stack's <code>Fit</code> is <code>Expand</code>.</td></tr><tr><td><strong>Corner Pinning</strong></td><td>Two non-opposing properties (e.g., <code>top</code> and <code>left</code>, or <code>bottom</code> and <code>right</code>).</td><td>Pins the child to a specific corner. The child maintains its intrinsic size and stays at a fixed offset from that corner, even if the Stack resizes.</td></tr><tr><td><strong>Axis Stretching &#x26; Aligning</strong></td><td>Two opposing properties (e.g., <code>left</code> and <code>right</code>, or <code>top</code> and <code>bottom</code>).</td><td>The child stretches along one axis and is positioned on the other axis by the parent Stack's <code>Alignment</code> property. <strong>Use Case:</strong> A header that stretches across the top of a card (by setting <code>top</code>, <code>left</code>, and <code>right</code>).</td></tr><tr><td><strong>Edge Pinning &#x26; Axis Stretching</strong></td><td>Three properties (e.g., <code>top</code>, <code>left</code>, and <code>right</code>).</td><td>Pins the child to one edge and stretches it along the opposite axis. For example, setting <code>top</code>, <code>left</code>, and <code>right</code> pins the child to the top edge and forces it to stretch horizontally.</td></tr><tr><td><strong>Full Stretch</strong></td><td>All four properties (<code>top</code>, <code>left</code>, <code>right</code>, and <code>bottom</code>).</td><td>Forces the child to stretch in both directions, filling the space defined by the four offsets. The child will grow and shrink dynamically as the parent Stack resizes. <strong>Use Case:</strong> A background image that should always fill the entire Stack.</td></tr></tbody></table>

<figure><img src="/files/9FFVhl2ZUAoJFikcmxsE" alt="A diagram explaining how the top, right, bottom, and left properties work to place a child within a Stack."><figcaption><p>The <code>Position</code> properties give you precise control over a child's layout behavior inside a Stack.</p></figcaption></figure>

#### Best Practices for Positioning

* **Avoid Over-Constraining**: You usually don't need to set all four properties (`top`, `bottom`, `left`, `right`). For example, to pin a widget to the top-left, you only need to set `top` and `left`. Setting all four can sometimes lead to unexpected layout behavior if the parent Stack's size changes.
* **Use `Alignment` for Simplicity**: For simple layouts where all children are aligned the same way (e.g., centered), it's easier to use a non-positioned child and set the Stack's `Alignment` property. Reserve positioning for widgets that need a unique location.
* **Responsive Design**: Be mindful of how your positioned children will behave on different screen sizes. Using a combination of `top`/`left` and `bottom`/`right` can help, but always test your layouts.

***

### Children of Stack

| Slot       | Description                                                                                                                                                     |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | The child widgets that are layered on top of each other. The first child is at the bottom, and subsequent children are stacked on top in the order they appear. |

***

### Default Properties

The Stack widget supports all [Default Properties](/ui-building-blocks/widgets/default-properties.md).

***

### Use Cases

The **Stack** widget lets you **place widgets on top of each other** (z-axis), instead of just side-by-side or top-to-bottom.

Use **Stack** when you want to:

* **Overlay content**
  * Text or gradient overlay on top of an image (e.g., banner with title on image)
  * Badge on a product image (SALE, NEW, % OFF)
  * Online/offline indicator dot on a profile avatar
* **Floating elements**
  * Floating action button over content
  * Positioned icons/buttons on the corners of a card or image
* **Custom layered UI**
  * Background decoration behind main content
  * Progress or status layer on top of another widget


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/layout-structure-widgets/stack.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.