<!--
{
  "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

[`var body: Self.Body`](/documentation/SwiftUI/Scene/body-swift.property)

The content and behavior of the scene.

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

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

### Watching for changes

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

Adds an action to perform when the given value changes.

[`func handlesExternalEvents(matching: Set<String>) -> some Scene`](/documentation/SwiftUI/Scene/handlesExternalEvents(matching:))

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

### Creating background tasks

[`func backgroundTask<D, R>(BackgroundTask<D, R>, action: (D) async -> R) -> some Scene`](/documentation/SwiftUI/Scene/backgroundTask(_:action:))

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

### Managing app storage

[`func defaultAppStorage(UserDefaults) -> some Scene`](/documentation/SwiftUI/Scene/defaultAppStorage(_:))

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

### Setting commands

[`func commands<Content>(content: () -> Content) -> some Scene`](/documentation/SwiftUI/Scene/commands(content:))

Adds commands to the scene.

[`func commandsRemoved() -> some Scene`](/documentation/SwiftUI/Scene/commandsRemoved())

Removes all commands defined by the modified scene.

[`func commandsReplaced<Content>(content: () -> Content) -> some Scene`](/documentation/SwiftUI/Scene/commandsReplaced(content:))

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

[`func keyboardShortcut(KeyboardShortcut?) -> some Scene`](/documentation/SwiftUI/Scene/keyboardShortcut(_:))

Defines a keyboard shortcut for opening new scene windows.

[`func keyboardShortcut(KeyEquivalent, modifiers: EventModifiers, localization: KeyboardShortcut.Localization) -> some Scene`](/documentation/SwiftUI/Scene/keyboardShortcut(_:modifiers:localization:))

Defines a keyboard shortcut for opening new scene windows.

### Sizing and positioning the scene

[`func defaultPosition(UnitPoint) -> some Scene`](/documentation/SwiftUI/Scene/defaultPosition(_:))

Sets a default position for a window.

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

Sets a default size for a window.

[`func defaultSize(width: CGFloat, height: CGFloat) -> some Scene`](/documentation/SwiftUI/Scene/defaultSize(width:height:))

Sets a default width and height for a window.

[`func defaultSize(width: CGFloat, height: CGFloat, depth: CGFloat) -> some Scene`](/documentation/SwiftUI/Scene/defaultSize(width:height:depth:))

Sets a default size for a volumetric window.

[`func defaultSize(Size3D, in: UnitLength) -> some Scene`](/documentation/SwiftUI/Scene/defaultSize(_:in:))

Sets a default size for a volumetric window.

[`func defaultSize(width: CGFloat, height: CGFloat, depth: CGFloat, in: UnitLength) -> some Scene`](/documentation/SwiftUI/Scene/defaultSize(width:height:depth:in:))

Sets a default size for a volumetric window.

[`func defaultWindowPlacement((WindowLayoutRoot, WindowPlacementContext) -> WindowPlacement) -> some Scene`](/documentation/SwiftUI/Scene/defaultWindowPlacement(_:))

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

[`func windowResizability(WindowResizability) -> some Scene`](/documentation/SwiftUI/Scene/windowResizability(_:))

Sets the kind of resizability to use for a window.

[`func windowIdealSize(WindowIdealSize) -> some Scene`](/documentation/SwiftUI/Scene/windowIdealSize(_:))

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

[`func windowIdealPlacement((WindowLayoutRoot, WindowPlacementContext) -> WindowPlacement) -> some Scene`](/documentation/SwiftUI/Scene/windowIdealPlacement(_:))

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

[`func windowManagerRole(WindowManagerRole) -> some Scene`](/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

[`func volumeWorldAlignment(WorldAlignmentBehavior) -> some Scene`](/documentation/SwiftUI/Scene/volumeWorldAlignment(_:))

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

[`func defaultWorldScaling(WorldScalingBehavior) -> some Scene`](/documentation/SwiftUI/Scene/defaultWorldScaling(_:))

Specify the world scaling behavior for the window.

### Configuring scene visibility

[`func defaultLaunchBehavior(SceneLaunchBehavior) -> some Scene`](/documentation/SwiftUI/Scene/defaultLaunchBehavior(_:))

Sets the default launch behavior for this scene.

[`func restorationBehavior(SceneRestorationBehavior) -> some Scene`](/documentation/SwiftUI/Scene/restorationBehavior(_:))

Sets the restoration behavior for this scene.

[`func persistentSystemOverlays(Visibility) -> some Scene`](/documentation/SwiftUI/Scene/persistentSystemOverlays(_:))

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

### Styling the scene

[`func immersionStyle(selection: Binding<any ImmersionStyle>, in: any ImmersionStyle...) -> some Scene`](/documentation/SwiftUI/Scene/immersionStyle(selection:in:))

Sets the style for an immersive space.

[`func menuBarExtraStyle<S>(S) -> some Scene`](/documentation/SwiftUI/Scene/menuBarExtraStyle(_:))

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

[`func upperLimbVisibility(Visibility) -> some Scene`](/documentation/SwiftUI/Scene/upperLimbVisibility(_:))

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

[`func windowStyle<S>(S) -> some Scene`](/documentation/SwiftUI/Scene/windowStyle(_:))

Sets the style for windows created by this scene.

[`func windowLevel(WindowLevel) -> some Scene`](/documentation/SwiftUI/Scene/windowLevel(_:))

Sets the window level of this scene.

[`func windowToolbarStyle<S>(S) -> some Scene`](/documentation/SwiftUI/Scene/windowToolbarStyle(_:))

Sets the style for the toolbar defined within this scene.

[`func windowToolbarLabelStyle(Binding<ToolbarLabelStyle>) -> some Scene`](/documentation/SwiftUI/Scene/windowToolbarLabelStyle(_:))

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

[`func windowToolbarLabelStyle(fixed: ToolbarLabelStyle) -> some Scene`](/documentation/SwiftUI/Scene/windowToolbarLabelStyle(fixed:))

Sets the label style of items in a toolbar.

### Configuring a document launcher scene

[`func documentBrowserContextMenu(([URL]?) -> some View) -> some Scene`](/documentation/SwiftUI/Scene/documentBrowserContextMenu(_:))

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

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

Sets the title displayed on the document launch card.

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

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

### Configuring a data model

[`func modelContext(ModelContext) -> some Scene`](/documentation/SwiftUI/Scene/modelContext(_:))

Sets the model context in this scene’s environment.

[`func modelContainer(ModelContainer) -> some Scene`](/documentation/SwiftUI/Scene/modelContainer(_:))

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

[`func 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

[`func environment<T>(T?) -> some Scene`](/documentation/SwiftUI/Scene/environment(_:))

Places an observable object in the scene’s environment.

[`func environment<V>(WritableKeyPath<EnvironmentValues, V>, V) -> some Scene`](/documentation/SwiftUI/Scene/environment(_:_:))

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

[`func environmentObject<T>(T) -> some Scene`](/documentation/SwiftUI/Scene/environmentObject(_:))

Supplies an `ObservableObject` to a view subhierarchy.

[`func transformEnvironment<V>(WritableKeyPath<EnvironmentValues, V>, transform: (inout V) -> Void) -> some Scene`](/documentation/SwiftUI/Scene/transformEnvironment(_:transform:))

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

### Interacting with dialogs

[`func dialogIcon(Image?) -> some Scene`](/documentation/SwiftUI/Scene/dialogIcon(_:))

Configures the icon used by alerts.

[`func dialogSeverity(DialogSeverity) -> some Scene`](/documentation/SwiftUI/Scene/dialogSeverity(_:))

Sets the severity for alerts.

[`func dialogSuppressionToggle(isSuppressed: Binding<Bool>) -> some Scene`](/documentation/SwiftUI/Scene/dialogSuppressionToggle(isSuppressed:))

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

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

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

### Supporting drag behavior

[`func windowBackgroundDragBehavior(WindowInteractionBehavior) -> some Scene`](/documentation/SwiftUI/Scene/windowBackgroundDragBehavior(_:))

Configures the behavior of dragging a window by its background.

### Configuring immersive scenes

[`func immersiveContentBrightness(ImmersiveContentBrightness) -> some Scene`](/documentation/SwiftUI/Scene/immersiveContentBrightness(_:))

Sets the content brightness of an immersive space.

[`func immersiveEnvironmentBehavior(ImmersiveEnvironmentBehavior) -> some Scene`](/documentation/SwiftUI/Scene/immersiveEnvironmentBehavior(_:))

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

### Deprecated symbols

[`func onChange<V>(of: V, perform: (V) -> Void) -> some Scene`](/documentation/SwiftUI/Scene/onChange(of:perform:))

Adds an action to perform when the given value changes.

## Relationships

### Conforming Types

[`ModifiedContent`](/documentation/SwiftUI/ModifiedContent)

[`UtilityWindow`](/documentation/SwiftUI/UtilityWindow)

[`Group`](/documentation/SwiftUI/Group)

[`DocumentGroup`](/documentation/SwiftUI/DocumentGroup)

[`Settings`](/documentation/SwiftUI/Settings)

[`WKNotificationScene`](/documentation/SwiftUI/WKNotificationScene)

[`RemoteImmersiveSpace`](/documentation/SwiftUI/RemoteImmersiveSpace)

[`AssistiveAccess`](/documentation/SwiftUI/AssistiveAccess)

[`WindowGroup`](/documentation/SwiftUI/WindowGroup)

[`MenuBarExtra`](/documentation/SwiftUI/MenuBarExtra)

[`ImmersiveSpace`](/documentation/SwiftUI/ImmersiveSpace)

[`Window`](/documentation/SwiftUI/Window)

[`DocumentGroupLaunchScene`](/documentation/SwiftUI/DocumentGroupLaunchScene)

[`AlertScene`](/documentation/SwiftUI/AlertScene)

---

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)