Contents

WidgetFamily

Values that define the widget’s size and shape.

Declaration

@preconcurrency enum WidgetFamily

Overview

Widgets can support one or more sizes, giving users the flexibility to configure their widgets however they like. Each widget size provides a different amount of space for detail, so consider which sizes work best for the type of information the widget displays. For more information about designing widgets, see Widgets or Complications.

You specify the sizes your widget supports using the supportedFamilies(_:) property modifier when defining your widget’s configuration.

struct GameStatusWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: "com.mygame.game-status",
            provider: GameStatusProvider(),
            placeholder: GameStatusPlaceholderView()
        ) { entry in
            GameStatusView(entry.gameStatus)
        }
        .configurationDisplayName("Game Status")
        .description("Shows an overview of your game status")
        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
    }
}

When WidgetKit needs to load a widget’s timeline, it calls the TimelineProvider class’s getTimeline(in:completion:) method. The system passes a TimelineProviderContext instance to the method’s context parameter. Use the context’s family property to determine the widget’s size and shape. For example, the WidgetFamily.systemSmall family represents a small, square widget on the Home Screen or Today View in iOS or iPadOS, while, in watchOS theWidgetFamily.accessoryCorner family appears as a widget-based complication in the corner of a watch face.

Use the WidgetFamily value to return the appropriate content given the widget’s size. For example, a WidgetFamily.systemSmall widget may focus on showing only the most critical data, such as a single image or a simple gauge, while a WidgetFamily.systemLarge widget can contain additional details, more-complex graphs, and even small blocks of text.

Topics

Accessing system families

Accessing accessory families

See Also

Widget creation