Understanding Container Background for Widget in iOS 17

Lee Kah Seng
4 min readSep 15, 2023

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.