<!--
{
  "availability" : [
    "iOS: 14.0.0 -",
    "iPadOS: 14.0.0 -",
    "macCatalyst: 14.0.0 -",
    "macOS: 11.0.0 -",
    "tvOS: 14.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 7.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "SwiftUI",
  "identifier" : "/documentation/SwiftUI/Scene",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "SwiftUI"
    ],
    "preciseIdentifier" : "s:7SwiftUI5SceneP"
  },
  "title" : "Scene"
}
-->

# Scene

A part of an app’s user interface with a life cycle managed by the
system.

```
@MainActor @preconcurrency protocol Scene
```

## Overview

You create an [`App`](/documentation/SwiftUI/App) by combining one or more instances
that conform to the `Scene` protocol in the app’s
[`body`](/documentation/SwiftUI/App/body-swift.property). You can use the built-in scenes that
SwiftUI provides, like [`WindowGroup`](/documentation/SwiftUI/WindowGroup), along with custom scenes
that you compose from other scenes. To create a custom scene, declare a
type that conforms to the `Scene` protocol. Implement the required
[`body`](/documentation/SwiftUI/Scene/body-swift.property) computed property and provide the
content for your custom scene:

```
struct MyScene: Scene {
    var body: some Scene {
        WindowGroup {
            MyRootView()
        }
    }
}
```

A scene acts as a container for a view hierarchy that you want to display
to the user. The system decides when and how to present the view hierarchy
in the user interface in a way that’s platform-appropriate and dependent
on the current state of the app. For example, for the window group shown
above, the system lets the user create or remove windows that contain
`MyRootView` on platforms like macOS and iPadOS. On other platforms, the
same view hierarchy might consume the entire display when active.

Read the [`scenePhase`](/documentation/SwiftUI/EnvironmentValues/scenePhase) environment
value from within a scene or one of its views to check whether a scene is
active or in some other state. You can create a property that contains the
scene phase, which is one of the values in the [`ScenePhase`](/documentation/SwiftUI/ScenePhase)
enumeration, using the [`Environment`](/documentation/SwiftUI/Environment) attribute:

```
struct MyScene: Scene {
    @Environment(\.scenePhase) private var scenePhase

    // ...
}
```

The `Scene` protocol provides scene modifiers, defined as protocol methods
with default implementations, that you use to configure a scene. For
example, you can use the [`onChange(of:perform:)`](/documentation/SwiftUI/Scene/onChange(of:perform:)) modifier to
trigger an action when a value changes. The following code empties a cache
when all of the scenes in the window group have moved to the background:

```
struct MyScene: Scene {
    @Environment(\.scenePhase) private var scenePhase
    @StateObject private var cache = DataCache()

    var body: some Scene {
        WindowGroup {
            MyRootView()
        }
        .onChange(of: scenePhase) { newScenePhase in
            if newScenePhase == .background {
                cache.empty()
            }
        }
    }
}
```

A type conforming to this protocol inherits `@preconcurrency @MainActor`
isolation from the protocol if the conformance is included in the type’s
base declaration:

```
struct MyCustomType: Transition {
    // `@preconcurrency @MainActor` isolation by default
}
```

Isolation to the main actor is the default, but it’s not required. Declare
the conformance in an extension to opt out of main actor isolation:

```
extension MyCustomType: Transition {
    // `nonisolated` by default
}
```

## Topics

### Creating a scene

[`body`](/documentation/SwiftUI/Scene/body-swift.property)

The content and behavior of the scene.

[`Body`](/documentation/SwiftUI/Scene/Body-swift.associatedtype)

The type of scene that represents the body of this scene.

### Watching for changes

[`onChange(of:initial:_:)`](/documentation/SwiftUI/Scene/onChange(of:initial:_:))

Adds an action to perform when the given value changes.

[`handlesExternalEvents(matching:)`](/documentation/SwiftUI/Scene/handlesExternalEvents(matching:))

Specifies the external events for which SwiftUI opens a new instance
of the modified scene.

### Creating background tasks

[`backgroundTask(_:action:)`](/documentation/SwiftUI/Scene/backgroundTask(_:action:))

Runs the specified action when the system provides a background task.

### Managing app storage

[`defaultAppStorage(_:)`](/documentation/SwiftUI/Scene/defaultAppStorage(_:))

The default store used by `AppStorage` contained within the scene and
its view content.

### Setting commands

[`commands(content:)`](/documentation/SwiftUI/Scene/commands(content:))

Adds commands to the scene.

[`commandsRemoved()`](/documentation/SwiftUI/Scene/commandsRemoved())

Removes all commands defined by the modified scene.

[`commandsReplaced(content:)`](/documentation/SwiftUI/Scene/commandsReplaced(content:))

Replaces all commands defined by the modified scene with the commands
from the builder.

[`keyboardShortcut(_:)`](/documentation/SwiftUI/Scene/keyboardShortcut(_:))

Defines a keyboard shortcut for opening new scene windows.

[`keyboardShortcut(_:modifiers:localization:)`](/documentation/SwiftUI/Scene/keyboardShortcut(_:modifiers:localization:))

Defines a keyboard shortcut for opening new scene windows.

### Sizing and positioning the scene

[`defaultPosition(_:)`](/documentation/SwiftUI/Scene/defaultPosition(_:))

Sets a default position for a window.

[`defaultSize(_:)`](/documentation/SwiftUI/Scene/defaultSize(_:))

Sets a default size for a window.

[`defaultSize(width:height:)`](/documentation/SwiftUI/Scene/defaultSize(width:height:))

Sets a default width and height for a window.

[`defaultSize(width:height:depth:)`](/documentation/SwiftUI/Scene/defaultSize(width:height:depth:))

Sets a default size for a volumetric window.

[`defaultSize(_:in:)`](/documentation/SwiftUI/Scene/defaultSize(_:in:))

Sets a default size for a volumetric window.

[`defaultSize(width:height:depth:in:)`](/documentation/SwiftUI/Scene/defaultSize(width:height:depth:in:))

Sets a default size for a volumetric window.

[`defaultWindowPlacement(_:)`](/documentation/SwiftUI/Scene/defaultWindowPlacement(_:))

Defines a function used for determining the default placement
of windows.

[`windowResizability(_:)`](/documentation/SwiftUI/Scene/windowResizability(_:))

Sets the kind of resizability to use for a window.

[`windowIdealSize(_:)`](/documentation/SwiftUI/Scene/windowIdealSize(_:))

Specifies how windows derived form this scene should determine their
size when zooming.

[`windowIdealPlacement(_:)`](/documentation/SwiftUI/Scene/windowIdealPlacement(_:))

Provides a function which determines a placement to use when windows
of a scene zoom.

[`windowManagerRole(_:)`](/documentation/SwiftUI/Scene/windowManagerRole(_:))

Configures the role for windows derived from `self` when
participating in a managed window context, such as full screen or
Stage Manager.

### Interacting with volumes

[`volumeWorldAlignment(_:)`](/documentation/SwiftUI/Scene/volumeWorldAlignment(_:))

Specifies how a volume should be aligned when moved in the world.

[`defaultWorldScaling(_:)`](/documentation/SwiftUI/Scene/defaultWorldScaling(_:))

Specify the world scaling behavior for the window.

### Configuring scene visibility

[`defaultLaunchBehavior(_:)`](/documentation/SwiftUI/Scene/defaultLaunchBehavior(_:))

Sets the default launch behavior for this scene.

[`restorationBehavior(_:)`](/documentation/SwiftUI/Scene/restorationBehavior(_:))

Sets the restoration behavior for this scene.

[`persistentSystemOverlays(_:)`](/documentation/SwiftUI/Scene/persistentSystemOverlays(_:))

Sets the preferred visibility of the non-transient system views
overlaying the app.

### Styling the scene

[`immersionStyle(selection:in:)`](/documentation/SwiftUI/Scene/immersionStyle(selection:in:))

Sets the style for an immersive space.

[`menuBarExtraStyle(_:)`](/documentation/SwiftUI/Scene/menuBarExtraStyle(_:))

Sets the style for menu bar extra created by this scene.

[`upperLimbVisibility(_:)`](/documentation/SwiftUI/Scene/upperLimbVisibility(_:))

Sets the preferred visibility of the user’s upper limbs, while an
[`ImmersiveSpace`](/documentation/SwiftUI/ImmersiveSpace) scene is presented.

[`windowStyle(_:)`](/documentation/SwiftUI/Scene/windowStyle(_:))

Sets the style for windows created by this scene.

[`windowLevel(_:)`](/documentation/SwiftUI/Scene/windowLevel(_:))

Sets the window level of this scene.

[`windowToolbarStyle(_:)`](/documentation/SwiftUI/Scene/windowToolbarStyle(_:))

Sets the style for the toolbar defined within this scene.

[`windowToolbarLabelStyle(_:)`](/documentation/SwiftUI/Scene/windowToolbarLabelStyle(_:))

Sets the label style of items in a toolbar and enables user customization.

[`windowToolbarLabelStyle(fixed:)`](/documentation/SwiftUI/Scene/windowToolbarLabelStyle(fixed:))

Sets the label style of items in a toolbar.

### Configuring a document launcher scene

[`documentBrowserContextMenu(_:)`](/documentation/SwiftUI/Scene/documentBrowserContextMenu(_:))

Adds to a `DocumentGroupLaunchScene` actions that accept
a list of selected files as their parameter.

[`documentLaunchTitle(_:)`](/documentation/SwiftUI/Scene/documentLaunchTitle(_:))

Sets the title displayed on the document launch card.

[`documentLaunchSubtitle(_:)`](/documentation/SwiftUI/Scene/documentLaunchSubtitle(_:))

Sets the subtitle displayed beneath the title on the document
launch card.

### Configuring a data model

[`modelContext(_:)`](/documentation/SwiftUI/Scene/modelContext(_:))

Sets the model context in this scene’s environment.

[`modelContainer(_:)`](/documentation/SwiftUI/Scene/modelContainer(_:))

Sets the model container and associated model context in this
scene’s environment.

[`modelContainer(for:inMemory:isAutosaveEnabled:isUndoEnabled:onSetup:)`](/documentation/SwiftUI/Scene/modelContainer(for:inMemory:isAutosaveEnabled:isUndoEnabled:onSetup:))

Sets the model container in this scene for storing the provided
model type, creating a new container if necessary, and also sets a model
context for that container in this scene’s environment.

### Managing the environment

[`environment(_:)`](/documentation/SwiftUI/Scene/environment(_:))

Places an observable object in the scene’s environment.

[`environment(_:_:)`](/documentation/SwiftUI/Scene/environment(_:_:))

Sets the environment value of the specified key path to the given value.

[`environmentObject(_:)`](/documentation/SwiftUI/Scene/environmentObject(_:))

Supplies an `ObservableObject` to a view subhierarchy.

[`transformEnvironment(_:transform:)`](/documentation/SwiftUI/Scene/transformEnvironment(_:transform:))

Transforms the environment value of the specified key path with the
given function.

### Interacting with dialogs

[`dialogIcon(_:)`](/documentation/SwiftUI/Scene/dialogIcon(_:))

Configures the icon used by alerts.

[`dialogSeverity(_:)`](/documentation/SwiftUI/Scene/dialogSeverity(_:))

Sets the severity for alerts.

[`dialogSuppressionToggle(isSuppressed:)`](/documentation/SwiftUI/Scene/dialogSuppressionToggle(isSuppressed:))

Enables user suppression of an alert with a custom suppression
message.

[`dialogSuppressionToggle(_:isSuppressed:)`](/documentation/SwiftUI/Scene/dialogSuppressionToggle(_:isSuppressed:))

Enables user suppression of an alert with a custom suppression
message.

### Supporting drag behavior

[`windowBackgroundDragBehavior(_:)`](/documentation/SwiftUI/Scene/windowBackgroundDragBehavior(_:))

Configures the behavior of dragging a window by its background.

### Configuring immersive scenes

[`immersiveContentBrightness(_:)`](/documentation/SwiftUI/Scene/immersiveContentBrightness(_:))

Sets the content brightness of an immersive space.

[`immersiveEnvironmentBehavior(_:)`](/documentation/SwiftUI/Scene/immersiveEnvironmentBehavior(_:))

Sets the immersive environment behavior that should apply when this
scene opens.

### Deprecated symbols

[`onChange(of:perform:)`](/documentation/SwiftUI/Scene/onChange(of:perform:))

Adds an action to perform when the given value changes.


---

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)