How it works
A SurroundingsEffect describes how a material treats the content that surrounds it — the area immediately outside the material's bounds — so that a translucent surface reads correctly against whatever is behind it. SwiftUI materials already blur and tint the content beneath them, but on their own they don't adjust the surrounding region to make the material feel separated from its backdrop; SurroundingsEffect supplies that adjustment as a single, reusable value. Reach for it when a glass or material surface needs more visual contrast against a busy or low-contrast background, and you want to dim or de-emphasize the surroundings rather than restyle the material itself. You apply it through the surroundingsEffect(_:) modifier, passing one of the built-in effect values.
Give the view a material to act on
SurroundingsEffect only has meaning on a surface that is itself translucent, so it pairs with a material background. In the example the effect is attached to a view whose
.background(.regularMaterial)provides the glassy surface; the surroundings effect then governs how the region around that material is treated.Apply it with surroundingsEffect(_:)
The
surroundingsEffect(_:)view modifier is the entry point: it takes a singleSurroundingsEffectvalue and applies it to the view's material surroundings. In the example.surroundingsEffect(.secondary)is chained directly after the material background so the effect operates on that surface.Choose an effect value
SurroundingsEffect exposes named values rather than raw numeric tuning, so you select an intent and let the system render it. The example uses
.secondary, a built-in value that lends a softer, recessed treatment to the surroundings — keeping the panel distinct without overpowering the content behind it.Order it relative to other modifiers
Because SwiftUI modifiers compose top-down, placement in the chain matters: the effect should follow the material it modifies. Here
.surroundingsEffect(.secondary)sits after.background(.regularMaterial)and before the outer.padding(), so the effect applies to the materializedText("Glass Panel")panel and not to the spacing added around it.
.surroundingsEffect(.secondary) to a different built-in value (or remove the modifier entirely) and watch how the area around the .regularMaterial panel shifts in emphasis against the background.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 SurroundingsEffectDemo: View {
var body: some View {
Text("Glass Panel")
.font(.headline)
.padding()
.background(.regularMaterial)
.surroundingsEffect(.secondary)
.padding()
}
}