Enumeration

ScenePhase

An indication of a scene's operational state.

---

Declaration

enum ScenePhase : Comparable

---

Overview

Getting Scene Status

The scenePhase environment value can easily be read in a scene to respond to whether the scene is active or in another state. It returns an enumeration of type ScenePhase.

struct StateAdaptingScene: Scene {
    @Environment(\.scenePhase) private var scenePhase
    var body: some Scene {
        WindowGroup {
            Text(scenePhase == .active ? "Active!" : "Inactive")
        }
    }
}

More

The system moves your app's Scene instances through phases that reflect a scene's operational state. You can trigger actions when the phase changes. Read the current phase by observing the scenePhase value in the Environment:

@Environment(\.scenePhase) private var scenePhase

How you interpret the value depends on where it's read from. If you read the phase from inside a View instance, you obtain a value that reflects the phase of the scene that contains the view. The following example uses the onChange(of:perform:) method to enable a timer whenever the enclosing scene enters the active phase and disable the timer when entering any other phase:

struct MyView: View {
    @ObservedObject var model: DataModel
    @Environment(\.scenePhase) private var scenePhase

    var body: some View {
        TimerView()
            .onChange(of: scenePhase) { phase in
                model.isTimerRunning = (phase == .active)
            }
    }
}

If you read the phase from within an App instance, you obtain an aggregate value that reflects the phases of all the scenes in your app. The app reports a value of active if any scene is active, or a value of inactive when no scenes are active. This includes multiple scene instances created from a single scene declaration; for example, from a WindowGroup. When an app enters the background phase, expect the app to terminate soon after. You can use that opportunity to free any resources:

@main
struct MyApp: App {
    @Environment(\.scenePhase) private var scenePhase

    var body: some Scene {
        WindowGroup {
            MyRootView()
        }
        .onChange(of: scenePhase) { phase in
            if phase == .background {
                // Perform cleanup when all scenes within
                // MyApp go to the background.
            }
        }
    }
}

If you read the phase from within a custom Scene instance, the value similarly reflects an aggregation of all the scenes that make up the custom scene:

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

    var body: some Scene {
        WindowGroup {
            MyRootView()
        }
        .onChange(of: scenePhase) { phase in
            if phase == .background {
                // Perform cleanup when all scenes within
                // MyScene go to the background.
            }
        }
    }
}

Availability

iOS 14.0+

macOS 11.0+

tvOS 14.0+

watchOS 7.0+

Topics

---

Instance Property

hashValue The hash value.

---

Instance Method

hash(into:) Hashes the essential components of this value by feeding them into the given hasher.

---

Type Method

<(a:b:) Returns a Boolean value indicating whether the value of the first argument is less than that of the second argument.

==(a:b:) Returns a Boolean value indicating whether two values are equal.

---

Case

active The scene is in the foreground and interactive.

background The scene isn't currently visible in the UI.

inactive The scene is in the foreground but should pause its work.