dpearson2699/swift-ios-skills / skills/swiftui-layout-components
swiftui-layout-components
VerifiedBuild SwiftUI layouts using stacks, grids, lists, scroll views, forms, and controls. Covers VStack/HStack/ZStack, LazyVGrid/LazyHGrid, List with sections and swipe actions, ScrollView with ScrollPosition and scroll-driven reveal surfaces, Form with validation, Toggle/Picker/Slider, .searchable, and overlay patterns. Use when building data-driven layouts, collection views, paged detail reveals, settings screens, search interfaces, or transient overlay UI.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.5 KB |
| evals/evals.json | config | 4.9 KB |
| references/form.md | markdown | 3.0 KB |
| references/grids.md | markdown | 6.5 KB |
| references/list.md | markdown | 3.7 KB |
| references/scrollview.md | markdown | 9.1 KB |
references/grids.md
View on GitHub# Grids
## Contents
- Intent
- Choosing the right grid type
- Column strategies
- Cell sizing and aspect ratio
- Example: adaptive icon grid
- Example: fixed 3-column media grid
- Example: sectioned grid
- Selection and interaction patterns
- Performance guardrails
- Accessibility and polish
- Pitfalls
## Intent
Use grids for dense visual collections where row-based layouts waste space or
make scanning harder.
Good fits:
- icon pickers
- media galleries
- template choosers
- settings tiles
- dashboards with repeatable cards
Default to `LazyVGrid` for vertically scrolling collections on iOS. Reach for
`Grid` when content is small and non-scrollable, or when you need explicit row
composition rather than a large lazy container.
## Choosing the right grid type
### `LazyVGrid`
Use for the common iPhone/iPad case: many items, vertical scrolling, and a
column definition that should adapt to width.
### `LazyHGrid`
Use when horizontal scrolling is the dominant interaction and rows are easier to
define than columns.
### `Grid`
Use when:
- the item count is small
- the content is mostly static
- row/column relationships matter more than lazy loading
- you need `GridRow` composition instead of a repeated collection layout
For large scrolling datasets, `LazyVGrid` is usually the safer default.
## Column strategies
### Adaptive columns
Use `.adaptive` when you want the number of columns to respond to available
width.
```swift
let columns = [GridItem(.adaptive(minimum: 120, maximum: 240))]
```
This is the best default for icon pickers, template choosers, and photo grids
that should scale naturally across iPhone and iPad sizes.
### Flexible columns
Use multiple `.flexible` columns when you want a predictable column count.
```swift
let columns = [
GridItem(.flexible(minimum: 100)),
GridItem(.flexible(minimum: 100)),
GridItem(.flexible(minimum: 100)),
]
```
This works well when design requires a fixed 2-column or 3-column rhythm.
### Fixed columns
Use `.fixed` only when the design truly requires exact widths. Fixed columns are
less resilient across device sizes and dynamic type changes.
## Cell sizing and aspect ratio
Grid cells should usually define their own shape without reading parent
geometry.
Preferred sizing tools:
- `.aspectRatio(1, contentMode: .fit)` for square thumbnails
- `.frame(maxWidth: .infinity)` when content should fill the available column
- internal padding instead of outer geometry math
Avoid `GeometryReader` inside lazy containers. It defeats lazy layout and adds
extra measurement work.
## Example: adaptive icon grid
```swift
let columns = [GridItem(.adaptive(minimum: 120, maximum: 240))]
LazyVGrid(columns: columns) {
ForEach(icons) { icon in
Button {
select(icon)
} label: {
ZStack(alignment: .bottomTrailing) {
Image(icon.previewName)
.resizable()
.aspectRatio(contentMode: .fit)
.clipShape(.rect(cornerRadius: 6))
if icon.isSelected {
Image(systemName: "checkmark.seal.fill")
.padding(4)
.tint(.green)
}
}
}
.buttonStyle(.plain)
.contentShape(Rectangle())
}
}
```
Why this works:
- adaptive columns scale across width classes
- square-ish cells come from image aspect ratio, not geometry reads
- the whole tile remains tappable
## Example: fixed 3-column media grid
```swift
LazyVGrid(
columns: [
.init(.flexible(minimum: 100), spacing: 4),
.init(.flexible(minimum: 100), spacing: 4),
.init(.flexible(minimum: 100), spacing: 4),
],
spacing: 4
) {
ForEach(items) { item in
ThumbnailView(item: item)
.aspectRatio(1, contentMode: .fit)
.clipShape(.rect(cornerRadius: 8))
}
}
```
Use this when the design language wants a consistent three-up gallery instead of
an adaptive count.
## Example: sectioned grid
Sectioned grids work well for grouped content like categories or recents.
```swift
LazyVGrid(columns: [GridItem(.adaptive(minimum: 140))]) {
ForEach(sections) { section in
Section {
ForEach(section.items) { item in
Tile(item: item)
}
} header: {
Text(section.title)
.font(.headline)
.frame(maxWidth: .infinity, alignment: .leading)
.padding(.top)
}
}
}
```
Keep headers visually lightweight. Dense grids lose scan efficiency when every
section header is oversized or heavily decorated.
## Selection and interaction patterns
Grid interactions should stay obvious and forgiving.
Useful defaults:
- make the entire cell tappable with `.contentShape(Rectangle())`
- show selection state in one consistent corner or border treatment
- keep hover/focus/pressed states subtle but visible
- avoid stacking too many overlays on every item
For multi-select grids, prefer clear selection affordances instead of hidden
state changes triggered only by long press.
## Performance guardrails
- Use `LazyVGrid` for large collections.
- Keep overlay count low in every cell.
- Downsample large images before display.
- Avoid expensive formatting or filtering in cell bodies.
- Prefer stable item identity in `ForEach`.
- Precompute grouped or filtered collections before rendering.
If scrolling stutters, profile image decoding, per-cell overlays, and repeated
state invalidation before changing the grid structure itself.
## Accessibility and polish
- Maintain clear visual grouping and consistent spacing.
- Test with Dynamic Type even if cells are primarily visual.
- Ensure VoiceOver labels describe the item and selection state.
- Use meaningful focus order on iPad and keyboard-driven flows.
- Avoid tiny hit targets even when cells are visually dense.
A dense grid should still feel calm and legible, not like a wall of competing
badges and borders.
## Pitfalls
- Avoid heavy overlays in every grid cell; it can be expensive.
- Don’t nest grids inside other grids without a clear reason.
- Don’t put filtering logic inline in `ForEach`.
- Don’t use fixed columns where adaptive columns better match the product goal.
- **Never place `GeometryReader` inside lazy containers** (`LazyVGrid`,
`LazyHGrid`, `LazyVStack`, `LazyHStack`). It forces eager measurement and
defeats lazy loading. Use `.aspectRatio` for sizing, or `.onGeometryChange`
if you need to read dimensions. The single-new-value overload is iOS 16+;
the old/new-value action overload is iOS 18+.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |