Environment & Preferences

What Is the Environment?

The SwiftUI environment is an implicit dependency injection system. It propagates values down the view hierarchy without explicit parameter passing. Any view can read environment values set by its ancestors.

struct AdaptiveView: View {
    @Environment(\.colorScheme) var colorScheme
    @Environment(\.horizontalSizeClass) var sizeClass
    @Environment(\.dynamicTypeSize) var typeSize
    
    var body: some View {
        VStack {
            Text("Color: \(colorScheme == .dark ? "Dark" : "Light")")
            Text("Size: \(sizeClass == .compact ? "Compact" : "Regular")")
            Text("Type Size: \(typeSize.debugDescription)")
        }
    }
}

How Environment Values Propagate

Environment values flow downward from parent to child. Each child receives the nearest ancestor's value:

NavigationView {
    ContentView()
        .environment(\.colorScheme, .dark)  // overrides for this subtree
}
// ContentView and all its children see .dark
// NavigationView itself uses the system default

Common System Environment Values

Using Environment for Adaptive Layouts

struct AdaptiveLayout: View {
    @Environment(\.horizontalSizeClass) var sizeClass
    
    var body: some View {
        if sizeClass == .regular {
            // iPad layout
            HStack {
                SidebarView()
                DetailView()
            }
        } else {
            // iPhone layout
            TabView {
                SidebarView()
                    .tabItem { Label("Menu", systemImage: "list") }
                DetailView()
                    .tabItem { Label("Detail", systemImage: "doc") }
            }
        }
    }
}

Dismiss Action

The .dismiss environment value provides a way to pop navigation stacks or dismiss sheets:

struct DetailView: View {
    @Environment(\.dismiss) var dismiss
    
    var body: some View {
        VStack {
            Text("Detail Content")
            Button("Go Back") {
                dismiss()
            }
        }
    }
}

openURL Action

struct LinkView: View {
    @Environment(\.openURL) var openURL
    
    var body: some View {
        Button("Visit Website") {
            if let url = URL(string: "https://example.com") {
                openURL(url)
            }
        }
    }
}

Defining Custom Keys

You can extend the environment with your own values by defining a key type that conforms to EnvironmentKey:

struct ThemeColors: EnvironmentKey {
    static let defaultValue = ThemeColors(
        primary: .blue,
        secondary: .gray,
        background: .white
    )
}

struct ThemeColors {
    let primary: Color
    let secondary: Color
    let background: Color
}

Registering the Key

Extend EnvironmentValues to provide a typed accessor:

extension EnvironmentValues {
    var themeColors: ThemeColors {
        get { self[ThemeColors.self] }
        set { self[ThemeColors.self] = newValue }
    }
}

Injecting Custom Values

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(\.themeColors, ThemeColors(
                    primary: .purple,
                    secondary: .orange,
                    background: Color(.systemGroupedBackground)
                ))
        }
    }
}

Using Custom Environment Values

struct StyledButton: View {
    @Environment(\.themeColors) var theme
    
    var body: some View {
        Button("Tap Me") { }
            .foregroundColor(.white)
            .background(theme.primary)
            .cornerRadius(8)
    }
}

struct ThemedView: View {
    @Environment(\.themeColors) var theme
    
    var body: some View {
        VStack {
            Text("Welcome")
                .foregroundColor(theme.primary)
            StyledButton()
        }
        .background(theme.background)
    }
}

Overriding Theme per Section

Different parts of the app can use different themes:

struct SettingsView: View {
    var body: some View {
        List {
            Section("Standard Theme") {
                ThemedView()
            }
            Section("Custom Theme") {
                ThemedView()
                    .environment(\.themeColors, ThemeColors(
                        primary: .green,
                        secondary: .mint,
                        background: .black
                    ))
            }
        }
    }
}

Multi-Value Environment Keys

For keys with multiple associated values, use a struct:

struct AppConfig: EnvironmentKey {
    static let defaultValue = AppConfig(
        apiBaseURL: "https://api.example.com",
        enableLogging: false,
        maxRetryCount: 3
    )
}

struct AppConfig {
    let apiBaseURL: String
    let enableLogging: Bool
    let maxRetryCount: Int
}

extension EnvironmentValues {
    var appConfig: AppConfig {
        get { self[AppConfig.self] }
        set { self[AppConfig.self] = newValue }
    }
}

Environment for Dependency Injection

Environment values work well for injecting services:

protocol AnalyticsService {
    func track(event: String, properties: [String: Any])
}

struct AnalyticsKey: EnvironmentKey {
    static let defaultValue: AnalyticsService = NoOpAnalytics()
}

extension EnvironmentValues {
    var analytics: AnalyticsService {
        get { self[AnalyticsKey.self] }
        set { self[AnalyticsKey.self] = newValue }
    }
}

// Usage in a view
struct BuyButton: View {
    @Environment(\.analytics) var analytics
    
    var body: some View {
        Button("Buy") {
            analytics.track(event: "purchase_initiated", properties: [:])
            // proceed with purchase
        }
    }
}

This approach avoids singletons and makes testing straightforward -- just inject a mock analytics service.

How EnvironmentValues Works

EnvironmentValues is a heterogeneous key-value store. Each key maps to a value of a specific type. When you access a key, you get the value set by the nearest ancestor, or the default if none was set.

// Internally, EnvironmentValues is a dictionary-like struct
// Each key is a static type, not a string
struct EnvironmentValues {
    subscript<Key: EnvironmentKey>(key: Key.Type) -> Key.Value {
        get { /* look up value */ }
        set { /* store value */ }
    }
}

Testing with Environment

Environment values make testing straightforward -- inject test values directly:

func testAdaptiveLayout() {
    let compactView = AdaptiveLayout()
        .environment(\.horizontalSizeClass, .compact)
    
    let regularView = AdaptiveLayout()
        .environment(\.horizontalSizeClass, .regular)
    
    // Snapshot or assert different layouts
}

Environment with Navigation

The .dismiss and .openURL actions are environment values:

struct ContentView: View {
    @Environment(\.dismiss) var dismiss
    @Environment(\.openURL) var openURL
    
    var body: some View {
        NavigationView {
            VStack {
                Button("Open Link") {
                    openURL(URL(string: "https://apple.com")!)
                }
                Button("Dismiss") {
                    dismiss()
                }
            }
            .navigationTitle("Home")
        }
    }
}

Conditional Environment Overrides

Override environment values conditionally based on state:

struct AppRoot: View {
    @State private var isReducedMotion = false
    
    var body: some View {
        ContentView()
            .environment(\
                \.,
                isReducedMotion ? .reduce : .standard
            )
    }
}

Environment and Preview

Use environment values in previews to test different configurations:

struct StyledButton_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            StyledButton()
                .environment(\.colorScheme, .light)
                .previewDisplayName("Light")
            
            StyledButton()
                .environment(\.colorScheme, .dark)
                .previewDisplayName("Dark")
        }
    }
}

Environment vs @EnvironmentObject

For simple configuration, use environment values. For complex stateful objects, use environment objects.