How it works
ContainerBackgroundPlacement names the region of a container that a background fill should occupy. SwiftUI containers like navigation stacks, tab views, and widgets each define their own backdrop area, and this type lets you target one of those areas by identity rather than by manually sizing and layering a view yourself. You reach for it whenever you call containerBackground(_:for:) and need to say which part of the surrounding container the supplied style should paint. It turns "draw something behind this container" into a precise, system-managed placement that adapts to the container's chrome.
Pass a placement to containerBackground(_:for:)
The placement is the second argument of the containerBackground(_:for:) modifier; the first is the ShapeStyle to fill that region with. Applying the modifier to a view associates a background with the nearest enclosing container that recognizes the given placement, which is why the call sits on the content inside the container rather than on the container itself. Here .containerBackground(.blue.gradient, for: .navigation) attaches a blue gradient to the navigation region.
Select the region with a placement value
Each value of ContainerBackgroundPlacement identifies one container surface. The .navigation value targets the backdrop of a NavigationStack (or NavigationSplitView), so the fill spans the navigation area behind your content and its title bar. In the example .navigation is what scopes .blue.gradient to the NavigationStack rather than to the inner VStack.
Let the enclosing container define the area
ContainerBackgroundPlacement carries no geometry of its own; the matching container supplies the bounds, safe-area behavior, and title-bar integration for the chosen region. Because the modifier is applied to the VStack inside the NavigationStack, SwiftUI walks outward to find the navigation container that owns the .navigation placement and lets it lay out the background to fit, including the area under the "Weather" navigationTitle.
Supply the fill as any ShapeStyle
The region is only the target; the appearance comes from the ShapeStyle you pair with the placement. Any conforming style works, including colors, materials, and gradients, so .blue.gradient fills the .navigation region with a gradient derived from the blue color. Swapping that first argument changes the look while the placement keeps the fill confined to the same container surface.
Example & preview
Press Run live & edit to compile it in your browser — then edit the Swift on the left and the preview re-renders live.
struct ContainerBackgroundPlacementDemo: View {
var body: some View {
NavigationStack {
VStack(spacing: 12) {
Image(systemName: "sun.max.fill")
.font(.largeTitle)
.foregroundStyle(.orange)
Text("72°")
.font(.system(size: 44, weight: .bold))
Text("Sunny")
.foregroundStyle(.secondary)
}
.padding()
.navigationTitle("Weather")
.containerBackground(
.blue.gradient,
for: .navigation
)
}
}
}