Understanding Container Background for Widget in iOS 17

This article is originally published at swiftsenpai.com.

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.

Issues you’ll encounter when updates to iOS 17

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.

Widget on the home screen vs. in standby mode

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: