Understanding Container Background for Widget in iOS 17

In the upcoming iOS 17 update, Apple once again expanded the use of widgets, making them available in more places, including the iPad lock screen and iPhone standby mode.

However, this update brings a new concept called “container background” to the table, which might lead to some errors in your existing WidgetKit projects. You might encounter messages like “Widget needs to adopt container background” on the preview canvas or unwanted content margins on the edges of your widget’s background.

In this article, let me walk you through what the container background is all about and show you how your existing widgets can adopt to this new concept. So, let’s get started.

---

The Purpose of The Container Background

In iOS 17, Apple introduced a new view modifier containerBackground(for:alignment:content:). This modifier allows developers to define the background view of a widget, making it easier for the system to adapt to different contexts.

For instance, if you have a systemSmall widget, the background will be visible when it’s displayed on the home screen. Whereas, when the widget is shown in the standby mode, the background will automatically be removed.

Now that you understand the purpose of using the container background modifier, let’s delve into how to use it in your own widget.

---

How to Adopt Container Background

Adopting the container background is a simple and straightforward process. All you need to do is add the containerBackground(for:alignment:content:) view modifier to your widget view and set your desired background view as its content.

For example, before iOS 17, a simple widget with a yellow background might look like this:

var body: some View {
    
    Text("Hello!")
        .frame(maxWidth: .infinity, maxHeight: .infinity)
        .background(.yellow)
}

After adopting the container background, the widget view code will become like this:

var body: some View {
    
    Text("Hello!")
        .containerBackground(for: .widget) {
            Color.yellow
        }
}

Furthermore, since the view modifier’s content is a view builder, we can now easily define a custom background view for our widgets. For instance, a widget with a multicolored background:

var body: some View {
    
    Text("Hello!")
        .containerBackground(for: .widget) {
            VStack(spacing: 0) {
                Color.yellow
                Color.green
            }
        }
}

Still remember the preview canvas error and content margins problem mentioned at the start of this article? Adopting the container background will get rid of both issues. How cool is that?

Pro Tip:

In order for the preview canvas to function correctly, it is still necessary to adopt container background even if your widget does not have a background. In such cases, simply provide an empty content:

.containerBackground(for: .widget) { }

With the preview canvas error out of the way, we can now preview the widget based on its context.

---

Disable Container Background Removal

At this stage, you might be wondering what to do if you don’t want the system to automatically remove the background view.

No need to worry, Apple has us covered. Simply configure the widget using the containerBackgroundRemovable() modifier, and we’re all set.

var body: some WidgetConfiguration {

    StaticConfiguration(
        kind: "com.SwiftSenpaiDemo.MyWidget",
        provider: MyWidgetTimelineProvider()
    ) { entry in
        MyWidgetView(entry: entry)
    }
    // Disable container background removal
    .containerBackgroundRemovable(false)
}

---

Further Readings

• How to Create Configurable Widgets With Static Options?
• How to Create Configurable Widgets With Dynamic Options?
• How to Fetch and Show Remote Data on a Widget?
• How to Update or Refresh a Widget?

---

Wrapping Up

There you have it. That’s how you can make your widget adopt to container background in iOS 17. If you like this article, be sure to follow me on Twitter and LinkedIn, and subscribe to my newsletter so that you won’t miss out on any of my upcoming iOS development-related articles.

Thanks for reading. 👨🏻‍💻

---

👋🏻 Hey!

While you’re still here, why not check out some of my favorite Mac tools on Setapp? They will definitely help improve your day-to-day productivity. Additionally, doing so will also help support my work.

• ✨ Bartender: Superpower your menu bar and take full control over your menu bar items.
• ✨ CleanShot X: The best screen capture app I’ve ever used.
• ✨ PixelSnap: Measure on-screen elements with ease and precision.
• ✨ iStat Menus: Track CPU, GPU, sensors, and more, all in one convenient tool.

---