<!--
{
  "availability" : [
    "visionOS: 26.0.0 -",
    "Xcode: 26.0.0 -"
  ],
  "documentType" : "article",
  "framework" : "visionOS",
  "identifier" : "/documentation/visionOS/associating-a-window-with-an-immersive-space",
  "metadataVersion" : "0.1.0",
  "role" : "sampleCode",
  "title" : "Associating a window with an immersive space"
}
-->

# Associating a window with an immersive space

Tightly couple a window with an immersive space for persistent controls.

## Overview

This sample code project demonstrates how you can present an immersive space alongside a window so that both remain active together.
Closing either the window or the immersive space closes the associated scene.
This approach is useful when a window and an immersive space need to stay synchronized.
For example, a shopping app can display a catalog with configuration options while showing a life-size replica of each selection in a person’s space, or a training app can present a checklist in the window that guides a person through tasks in the immersive experience.

![An app transitioning in and out of the immersive space with a pushed window.](videos/com.apple.visionOS/sample-scenes-02-associating-a-window-with-an-immersive-space.mov)

See [Embedding controls in an immersive space](/documentation/visionOS/embedding-controls-in-an-immersive-space) for an alternative to this approach using <doc://com.apple.documentation/documentation/RealityKit/ViewAttachmentComponent>.

## Create three scenes

In the sample, <doc://com.apple.documentation/documentation/SwiftUI/EnvironmentValues/pushWindow> opens a new window on top of the existing window.
The system removes the existing window from view, and it enters the background scene phase.
When the sample uses <doc://com.apple.documentation/documentation/SwiftUI/EnvironmentValues/pushWindow> at the same time as <doc://com.apple.documentation/documentation/SwiftUI/EnvironmentValues/openImmersiveSpace>, the resulting  app consists of three scenes: the backgrounded scene that called <doc://com.apple.documentation/documentation/SwiftUI/EnvironmentValues/pushWindow>, the new visible window that <doc://com.apple.documentation/documentation/SwiftUI/EnvironmentValues/pushWindow> opens, and the immersive scene.

```swift
.onChange(of: appModel.immersiveSpaceState) {
    if appModel.immersiveSpaceState == .open {
        pushWindow(id: SceneID.controlsScene.rawValue)
    }
}
```

The app can dismiss its own scenes as long as it’s not the last scene; the person decides when to dismiss the last scene, closing the app.
The sample can close the scene that <doc://com.apple.documentation/documentation/SwiftUI/EnvironmentValues/pushWindow> opens at any time to dismiss the pushed window and show the backgrounded window.
When either the immersive scene or the system controls scene disappears, the sample app closes the other scene, which reactivates the backgrounded scene.

## Dismiss the window and immersive space together

When the immersive space opens, the sample calls <doc://com.apple.documentation/documentation/SwiftUI/EnvironmentValues/pushWindow> with the controls scene identifier inside of `ContentView`.
The new controls scene replaces `ContentView`, and `ContentView` moves to the background.

The pushed window’s view uses two view modifiers to close the immersive space and the pushed window at the same time.
The sample uses <doc://com.apple.documentation/documentation/SwiftUI/View/onDisappear(perform:)> to detect when the system removes the pushed window from the view hierarchy and then to dismiss the immersive space.
The sample app calls <doc://com.apple.documentation/documentation/SwiftUI/EnvironmentValues/dismiss> to dismiss the pushed window when the immersive space closes.

```swift
.onDisappear {
    Task {
        if appModel.immersiveSpaceState == .open {
            await dismissImmersiveSpace()
        }
    }
}
.onChange(of: appModel.immersiveSpaceState) {
    if appModel.immersiveSpaceState == .closed {
        dismiss()
    }
}
```

## See Also

### Managing multiple scenes

[Handling the window life cycle with multiple scenes](/documentation/visionOS/handling-the-window-life-cycle-with-multiple-scenes)

Track scene state across different window types.

[Embedding controls in an immersive space](/documentation/visionOS/embedding-controls-in-an-immersive-space)

Keep controls visible throughout an immersive experience by displaying them in a window or a view attachment.



---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)