Layout widgets
Layout widgets answer one question before anything else in the user interface does: how should space be divided, constrained, layered, and protected?
That makes them different from display widgets, which mostly show information, and input widgets, which mostly collect intent. Layout widgets decide the structure the rest of the user interface lives inside.
How to choose among layout widgets
Start with the simplest structure that matches the reading order.
Use a vertical flow first when the screen reads top to bottom. Use a horizontal flow when side-by-side comparison matters. Move to grids when repeated content benefits from a matrix. Use stacks and positioned layouts when layering is the point, not just ordinary arrangement.
Once the overall structure is clear, add helpers for centering, safe areas, ratio preservation, wrapping, or split panes where those patterns are genuinely needed.
Core linear and constraint widgets
These are the first widgets to reach for on most screens.
| Widget | Dedicated page | When to choose it |
|---|---|---|
Container | Container | You need one child plus padding, sizing, background, or constraint control |
Row | Row | Children should stay in a horizontal sequence |
Column | Column | Children should stay in a vertical sequence |
Spacer | Spacer | You need fixed or flexible empty space |
Scroll | Scroll | Content may legitimately exceed the viewport |
Align | Align | A child needs alignment inside available bounds |
Center | Center | You only need centered placement |
Higher-level stack and flow helpers
These widgets express layout patterns that are already common enough to deserve named helpers.
| Widget | Dedicated page | When to choose it |
|---|---|---|
HStack | HStack | You want a higher-level horizontal stack helper |
VStack | VStack | You want a higher-level vertical stack helper |
Wrap | Wrap | Repeated items should flow onto new lines as width changes |
SimpleGrid | SimpleGrid | You want a simpler grid authoring surface |
SplitView | SplitView | The screen is naturally a split-pane layout |
SplitDirection | SplitDirection | You need the supporting split orientation type |
Grid and layered layouts
Use these when a purely linear layout is no longer the right shape.
| Widget | Dedicated page | When to choose it |
|---|---|---|
Grid | Grid | Repeated content belongs in rows and columns |
GridItem | GridItem | A child needs span or placement rules inside a grid |
ZStack | ZStack | Children should share the same visual area in layers |
Positioned | Positioned | A layered child needs explicit placement |
Overlay | Overlay | Content and overlay content share the same region deliberately |
Edge protection, ratios, and adaptive helpers
These widgets become important when a layout needs to react to host conditions or special constraints.
| Widget | Dedicated page | When to choose it |
|---|---|---|
SafeArea | SafeArea | Content should avoid host insets such as mobile safe areas |
AspectRatio | AspectRatio | A child should preserve a specific width-to-height ratio |
LayoutBuilder | LayoutBuilder | The build output depends directly on current constraints |
absolute_fill(...) | absolute_fill | A child should fill the stacked bounds |
Clip | Clip | A child must be clipped to a region |
Transform | Transform | A child needs visual transformation |
Composite | Composite | You need composition or repaint-boundary control |
FocusScope | FocusScope | Focus traversal should stay within a layout region |
Practical cross-reference
If the next question is really about themed or responsive screen composition, pair this page with the guide on Layout and widgets. If the next question is about a particular widget family rather than structure, return to the Widget catalog.