How it works
ImmersiveEnvironmentBehavior is a set of constants that tells SwiftUI how an immersive environment should coexist with the world around it on visionOS. When you present immersive content, the system needs to know whether that content should take over the wearer's surroundings or blend with them; this type names those choices so you can express your intent declaratively. Reach for it whenever you want to soften an immersive scene — for example, letting your rendered environment sit alongside the passthrough view of the room rather than replacing it.
Choose a behavior constant
ImmersiveEnvironmentBehavior exposes its options as static constants on the type, so you pick the behavior by name rather than constructing a value. Here the code selects
.coexist, which keeps the immersive environment present while still allowing the surrounding passthrough to show through.Apply it with immersiveEnvironmentBehavior(_:)
You attach the behavior to your scene through the
immersiveEnvironmentBehavior(_:)view modifier, which takes an ImmersiveEnvironmentBehavior value and propagates it to the immersive content in that part of the hierarchy. In the example it is applied to the paddedVStack, so the chosen behavior governs how that content's environment is presented.Place the modifier where the environment lives
Because the behavior flows down through the view tree, position the modifier on the container that owns the immersive content so the setting reaches everything inside it. The example puts
.immersiveEnvironmentBehavior(.coexist)after.padding()on theVStackthat holds theImageandTextlabels, scoping the behavior to that subtree.Read the constant's intent
Each ImmersiveEnvironmentBehavior constant describes a distinct relationship between your environment and the real world, which is why the type is documented as constants that specify how an immersive environment behaves. The
.coexistvalue chosen here signals that the environment should not fully occlude reality — matching the example's caption,Coexists with passthrough.
.immersiveEnvironmentBehavior(.coexist) to a different ImmersiveEnvironmentBehavior constant to see how the environment's relationship with passthrough shifts.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 ImmersiveEnvironmentBehaviorDemo: View {
var body: some View {
VStack(spacing: 12) {
Image(systemName: "mountain.2.fill")
.font(.system(size: 44))
.foregroundStyle(.teal)
Text("Immersive Environment")
.font(.headline)
Text("Coexists with passthrough")
.font(.caption)
.foregroundStyle(.secondary)
}
.padding()
.immersiveEnvironmentBehavior(.coexist)
}
}