49. Supporting WidgetKit Size Families

In the chapter titled “Building Widgets with SwiftUI and WidgetKit”, we learned that a widget is able to appear in small, medium and large sizes. The project created in the previous chapter included a widget view designed to fit within the small size format. Since the widget did not specify the supported sizes, it would still be possible to select a large or medium sized widget from the gallery and place it on the home screen. In those larger formats, however, the widget content would have filled only a fraction of the available widget space. If larger widget sizes are to be supported, the widget should be designed to make full use of the available space.

In this chapter, the WidgetDemo project created in the previous chapter will be modified to add support for the medium widget size.

49.1 Supporting Multiple Size Families

Begin by launching Xcode and loading the WidgetDemo project from the previous chapter. As outlined above, this phase of the project will add support for the medium widget size (though these steps apply equally to adding support for the large widget size).

In the absence of specific size configuration widgets are, by default, configured to support all three size families. To restrict a widget to specific sizes, the supportedFamilies() modifier must be applied to the widget configuration.

To restrict the widget to only small and medium sizes for the WidgetDemo project, edit the WeatherWidget.swift file and modify the WeatherWidget declaration to add the modifier. Also take this opportunity to modify the widget display name and description:

@main

struct WeatherWidget: Widget {

    private let kind: String = "WeatherWidget"

 

    public var body: some WidgetConfiguration ...

49.2 Adding Size Support to the Widget View

The changes made to the widget configuration mean that the widget can be displayed in either small or medium size. To make the widget adaptive, the widget view needs to identify the size in which it is currently being displayed. This can be achieved by accessing the widgetFamily property of the SwiftUI environment. Remaining in the WeatherWidget.swift file, locate and edit the WeatherWidgetEntryView declaration to obtain the widget family setting from the environment:

struct WeatherWidgetEntryView: View {

    var entry: Provider.Entry

    

    @Environment(\.widgetFamily) var widgetFamily

.

.

Next, embed the subview in a horizontal stack and conditionally display the image for the entry if the size is medium:

struct WeatherWidgetEntryView : View {

    var entry: Provider.Entry

 

    @Environment(\.widgetFamily...

49.3 Summary

WidgetKit supports small, medium and large widget size families and, by default, a widget is assumed to support all three formats. In the event that a widget only supports specific sizes, WidgetKit needs to be notified using a widget configuration modifier.

To fully support a size format, a widget should take steps to detect the current size and provide a widget entry layout which makes use of the available space allocated to the widget on the device screen. This involves accessing the SwiftUI environment widgetFamily property and using it as the basis for conditional layout declarations within the widget view.

Now that widget size family support has been added to the project, the next chapter will add some interactive support to the widget in the form of deep linking into the companion app and widget configuration.