swiftuiios17ios18xcode16

.containerBackground availability incorrect?

I've been meaning to try .containerBackground for a while, having seen it introduced with iOS 17, but now that I did I am left confused, because XCode claims it's available only on iOS 18 or newer:

Compiling failed: 'navigation' is only available in iOS 18.0 or newer

However, the documentation clearly states iOS 17+. I looked it up and I haven't found anything about it not being available in iOS 17+.

So am I using it wrong, or what's going on here?

Here's an MRE, assuming your project is setup to target iOS 17+, in order to get the error.

import SwiftUI

struct ContainerBackgroundTest: View {
    var body: some View {
        NavigationStack {
            // if #available(iOS 18.0, *) {
                VStack {
                    ContentUnavailableView {
                        Label("containerBackground(_:for:)", systemImage: "bubbles.and.sparkles")
                        
                    } description: {
                        let availability = """
        iOS 17.0+ | iPadOS 17.0+ | Mac Catalyst 17.0+ | macOS 14.0+ | tvOS 17.0+ | visionos 1.0+ | watchOS 10.0+
        """
                        Text("Sets the container background of the enclosing container using a view.")
                        Text(availability)
                    } actions: {
                        Button {
                            //action here...
                        } label: {
                            Text("Report bad documentation")
                        }
                    }
                }
                .navigationTitle("Home")
                .containerBackground(.cyan.gradient.opacity(0.6), for: .navigation)
            // } else {
            //  // Fallback on earlier versions
            // }

        }
    }
}

#Preview {
        ContainerBackgroundTest()
}

enter image description here

Solution

  • The error message made this very clear. It is navigation that is unavailable, not the .containerBackground modifier itself.

    In iOS 17, you can still use .containerBackground to modify the background of other ContainerBackgroundPlacements. In fact, Xcode's template for a widget extension includes

    .containerBackground(.fill.tertiary, for: .widget)

    The other 3 ContainerBackgroundPlacements available on iOS 17 are:

    which are all a part of StoreKit.