Simplifying environment values with the Entry Macro

You need to use Xcode 16 Beta or later to use the Entry macro.

During WWDC24, Apple introduced the Entry macro to simplify the creation of custom EnvironmentValues. It’s important to remember that EnvironmentValues is a structure provided by SwiftUI to propagate values across views using the .environment modifier and to access them using the @Environment property wrapper.

A Little History

In the past, to add a value to EnvironmentValues, you had to:

1. Create a structure that conforms to the EnvironmentKey protocol, which serves as a key to access the value in the environment and requires a default value. For example, to create a value that specifies a primary color:

private struct PrimaryColorKey: EnvironmentKey  {
  static var defaultValue: Color = .black
}

2. Extend EnvironmentValues to add your custom value through a computed property:

extension EnvironmentValues {
  var primaryColor: Color {
    get { self[PrimaryColorKey.self] }
    set { self[PrimaryColorKey.self] = newValue }
  }
}

3. Propagate your custom value in your views:

ContentView()
  .environment(\.primaryColor, .red)

4. Use your value via the @Environment property wrapper inside the views where you applied the .environment modifier or child views, in this example within ContentView:

@Environment(\.primaryColor) var primaryColor

Present

With the Entry macro, it’s no longer necessary to create a structure that conforms to the EnvironmentKey protocol, and the creation of computed properties in the EnvironmentValues extension is simplified. This means you can skip the first step, simplify the second, and continue with the remaining steps as before. To use the macro, you need to create a variable marked with @Entry within the EnvironmentValues extension. Following the previous example, to create a value that specifies a primary color using Entry:

extension EnvironmentValues {
  @Entry var primaryColor: Color = .black
}

If you expand the macro, you can see that it still uses EnvironmentKey and the computed property:

@Entry var primaryColor: Color = .black
{
    get {
        self[__Key_primaryColor.self]
    }
    set {
        self[__Key_primaryColor.self] = newValue
    }
}

private struct __Key_primaryColor: SwiftUI.EnvironmentKey {
    typealias Value = Color
    static let defaultValue: Value = .black
}

This means that EnvironmentKey is not being marked as deprecated, so you can continue maintaining your EnvironmentKey while adding new values using Entry.

Besides using Entry for EnvironmentValues, you can also use it to create Transaction Values, ContainerValues, and FocusedValues.

Compatibility

Entry can be used starting from the following versions of Apple’s operating systems:

• iOS 13.0+.
• iPadOS 13.0+.
• Mac Catalyst 13.0+.
• macOS 10.15+.
• tvOS 13.0+.
• visionOS 1.0+.
• watchOS 6.0+.

Conclusion

The SwiftUI Entry macro allows you to significantly simplify the creation and management of custom values in your EnvironmentValues. Don’t wait to improve your workflow and make your code cleaner 😉.