Stack

The Stack widget is essential for creating complex, layered user interfaces.

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.

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.

The Stack widget enables complex, layered user interfaces.

---

Use Cases

The Stack widget is ideal for scenarios where you need to overlap widgets, such as:

• Text Overlays: Placing text (like a title or a price) over an image.

• Badges and Icons: Adding a notification badge to an icon or a "New" banner to a product card.

• Complex UI Elements: Building custom UI elements like user profile headers, where an avatar overlaps a background image.

• Floating Action Buttons: Creating custom floating buttons that are not tied to the Scaffold.

---

Properties

Stack Properties

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

---

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

Property	Description
Top	The distance to offset the child from the top edge of the Stack.
Bottom	The distance to offset the child from the bottom edge of the Stack.
Left	The distance to offset the child from the left edge of the Stack.
Right	The distance to offset the child from the right edge of the Stack.

Positioning Behaviors

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

Behavior	Properties Set	Description & Use Case
Non-Positioned	None (top, left, right, bottom are all unset).	The child's position is determined by the parent Stack's Alignment property. The child retains its natural size, unless the Stack's Fit is Expand.
Corner Pinning	Two non-opposing properties (e.g., top and left, or bottom and right).	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.
Axis Stretching & Aligning	Two opposing properties (e.g., left and right, or top and bottom).	The child stretches along one axis and is positioned on the other axis by the parent Stack's Alignment property. Use Case: A header that stretches across the top of a card (by setting top, left, and right).
Edge Pinning & Axis Stretching	Three properties (e.g., top, left, and right).	Pins the child to one edge and stretches it along the opposite axis. For example, setting top, left, and right pins the child to the top edge and forces it to stretch horizontally.
Full Stretch	All four properties (top, left, right, and bottom).	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. Use Case: A background image that should always fill the entire Stack.

The Position properties give you precise control over a child's layout behavior inside a Stack.

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.

---

Default Properties

The Stack widget supports all Default Properties, such as Visibility and Alignment (for positioning the Stack itself within a parent).

---