In SwiftUI, how do listStyle and the row modifiers listRowInsets, listRowSeparator and listRowBackground shape a List, and where must each one go?
answer
- style for the whole list
- row settings the List reads
- on the row's outermost view
- the style has the final say
basics
~20 slistStyle(_:) picks the whole list's look, while listRowInsets, listRowSeparator and listRowBackground are row settings the containing List reads from each row view, so they go on the row's outermost view, not on a nested subview.
solid answer
~40 s`listStyle(_:)` sets the style for lists inside the view it modifies: `.insetGrouped`, `.plain`, `.grouped`, `.inset` and `.sidebar` on iOS. The row modifiers configure how the **containing `List`** draws a row: `listRowInsets(_:)` replaces the row's padding, `listRowBackground(_:)` puts a view behind it, and `listRowSeparator(_:edges:)` (iOS 15) states a preference for its separators, which Apple says the list style finally decides. The interface shows the insets and background modifiers writing view traits, values the `List` reads from its row views, so put them on the outermost view each `ForEach` iteration returns; on a `Text` nested inside the row's `HStack` they do not reach the list. Section-level knobs are `listSectionSeparator(_:edges:)` and `listSectionSpacing(_:)` from iOS 17.
code
swift · 31 linesimport SwiftUI
struct Message: Identifiable { let id = UUID(); var subject: String; var isFlagged = false }
struct InboxView: View {
let today: [Message]
let older: [Message]
var body: some View {
List {
Section("Today") {
ForEach(today) { message in
HStack {
Text(message.subject)
Spacer()
if message.isFlagged { Image(systemName: "flag.fill") }
}
.listRowInsets(EdgeInsets(top: 8, leading: 20, bottom: 8, trailing: 16))
.listRowSeparator(.hidden, edges: .top)
.listRowBackground(message.isFlagged ? Color.orange.opacity(0.15) : nil)
}
}
Section("Older") {
ForEach(older) { Text($0.subject) }
}
.listSectionSeparator(.hidden, edges: .bottom)
}
.listStyle(.insetGrouped)
.listSectionSpacing(.compact)
}
}go deeper
Recall the names: listStyle for the whole list, listRowInsets, listRowBackground and listRowSeparator for rows, listSectionSpacing for gaps between sections.
Explain that row modifiers are read by the containing List from each row view, why placement matters, and why the style decides separators.
Spot dead row modifiers in review, check separators in the real style, and know when a design fights List enough to warrant a lazy stack.
Wrap the house list styling in shared row and list modifiers so screens stay consistent and new styles land in one place.
## Two layers of styling Styling a SwiftUI `List` happens at two levels, and mixing them up is the source of most "my modifier does nothing" reports. - **List level.** `listStyle(_:)` "sets the style for lists within this view". It chooses the overall look: grouped cards, edge-to-edge rows, a sidebar. Apply it once, on the `List` or an ancestor. - **Row and section level.** Modifiers whose names start with `listRow` or `listSection` do not draw anything themselves. They tell the **containing `List`** how to lay out and decorate one row or one section. ## The built-in list styles on iOS | Style | Look | Available | |---|---|---| | `.automatic` | SwiftUI chooses based on platform and context | iOS 13 | | `.plain` | edge-to-edge rows, no grouping inset | iOS 13 | | `.grouped` | sections drawn as grouped blocks | iOS 13 | | `.inset` | rows inset from the edges | iOS 14 | | `.insetGrouped` | sections as rounded, inset cards | iOS 14 | | `.sidebar` | sidebar look; a `Section` with `isExpanded` shows a disclosure indicator | iOS 14 | Other styles such as `.bordered` (macOS), `.carousel` and `.elliptical` (watchOS) are unavailable on iOS. Apple's documentation also suggests a `LazyVStack` when you want none of the platform styling, such as separators or disclosure indicators; that container is covered in the lesson on lazy stacks. ## Row modifiers and where they go The row modifiers are **row settings**. In the SDK's interface, `listRowInsets(_:)` and `listRowBackground(_:)` are written as view traits, values a container reads from the views it lays out. Practically: 1. Apply them to the **row view** — the outermost view a `ForEach` iteration returns, or a static row inside the `List` builder. 2. Do **not** bury them on a subview inside the row's `HStack`; that subview is a child of the stack, not a row the `List` sees. 3. Outside a `List`, in a `VStack` or `LazyVStack`, nothing reads them, so they have no effect. What each one does: - **`listRowInsets(_:)`** takes `EdgeInsets?` and replaces the default padding around the row's content; `nil` keeps the default. Apple notes that on iOS 18 and earlier row content can grow slightly into the insets, so effective vertical insets may look smaller than set. - **`listRowBackground(_:)`** places any view behind the row — a color, a material, a shape; `nil` keeps the style's default. - **`listRowSeparator(_:edges:)`**, from iOS 15, sets visibility for the row's top or bottom separator. Apple calls it a **preference**: the list style is the final arbiter, and a style may not draw a top separator at all. `listRowSeparatorTint(_:edges:)` recolors it. - **`listRowSpacing(_:)`**, from iOS 15, sets vertical space between rows, applied to the list. ## Section-level settings - **`listSectionSeparator(_:edges:)`** and **`listSectionSeparatorTint(_:edges:)`** control the separators that belong to a section rather than to rows. - **`listSectionSpacing(_:)`**, from iOS 17, sets the gap between adjacent sections with `.default`, `.compact`, `.custom(_:)` or a `CGFloat`. Apply it to the `List` for all sections. ```swift ForEach(today) { message in HStack { Text(message.subject); Spacer() } .listRowInsets(EdgeInsets(top: 8, leading: 20, bottom: 8, trailing: 16)) .listRowSeparator(.hidden, edges: .top) } ``` ## When a row modifier seems to do nothing Work through the usual causes in order: 1. **Placement.** Is the modifier on the outermost view of the row, or on a child inside an `HStack` or `VStack`? Move it out. 2. **Container.** Is the view actually inside a `List`? A `ScrollView` with a `LazyVStack` has rows only in name, and nothing reads the setting. 3. **Style.** For separators, does the current style draw that edge at all? Try the same code with `.plain` to see whether the style is overriding the preference. 4. **Layer.** Is the line a row separator or a section separator? The two have separate modifiers. 5. **Release.** Is the overload you call available at your deployment target? The edge-and-length form of `listRowInsets` arrived later than the `EdgeInsets` form. ## Review checklist - One `listStyle(_:)` per list, chosen for the screen, not a stack of overrides. - Row modifiers sit on the row's outermost view, after any wrapping container. - Hidden separators are checked in the actual style, because the style may override the preference. - Spacing between sections uses `listSectionSpacing(_:)` rather than empty spacer rows. - A fully custom look that fights every list default is a sign the screen wants a lazy stack instead.
- Why might a hidden top separator still show after listRowSeparator(.hidden, edges: .top)?Apple describes `listRowSeparator(_:edges:)` as a preference to the containing `List`, with the list style as the final arbiter. Also check whether the line belongs to the section rather than the row: section separators are controlled by `listSectionSeparator(_:edges:)`.
- listRowInsets works when applied to a Text deep inside the row's HStack
- listRowSeparator(.hidden) always wins over the list style
- Row modifiers also style rows of a LazyVStack
- listRowInsets was added in iOS 26
- listRowSpacing changes the gap between sections