Values that define the widget's size and shape.
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](https://developer.apple.com/design/human-interface-guidelines/widgets/overview/introduction/)
or [Complications](https://developer.apple.com/design/human-interface-guidelines/watchos/overview/complications/).
> Note: The sizes of widgets may vary across devices. Your widget content
should be flexible and avoid using fixed values.
You specify the sizes your widget supports using the <doc://com.apple.documentation/documentation/swiftui/widgetconfiguration/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
``WidgetKit/TimelineProvider`` class's
``WidgetKit/TimelineProvider/getTimeline(in:completion:)`` method. The system
passes a ``WidgetKit/TimelineProviderContext`` instance to the method's
`context` parameter. Use the context's
``WidgetKit/TimelineProviderContext/family`` property to determine the
widget's size and shape. For example, the
``WidgetKit/WidgetFamily/systemSmall`` family represents a small, square
widget on the Home Screen or Today View in iOS or iPadOS, while, in watchOS
the``WidgetKit/WidgetFamily/accessoryCorner`` family appears as
a widget-based complication in the corner of a watch face.
Use the ``WidgetKit/WidgetFamily`` value to return the appropriate content
given the widget's size. For example,
a ``WidgetKit/WidgetFamily/systemSmall`` widget may focus on showing only
the most critical data, such as a single image or a simple gauge, while
a ``WidgetKit/WidgetFamily/systemLarge`` widget can contain additional
details, more-complex graphs, and even small blocks of text.
Members (4)
get · iOS 14.0+
description
TypeScript
getDescription($self: WidgetFamily): string
Swift declaration
var description: String { get }
A textual representation of this instance.
Calling this property directly is discouraged. Instead, convert an
instance of any type to a string by using the `String(describing:)`
initializer. This initializer works with any type, and uses the custom
`description` property for types that conform to
`CustomStringConvertible`:
struct Point: CustomStringConvertible {
let x: Int, y: Int
var description: String {
return "(\(x), \(y))"
}
}
let p = Point(x: 21, y: 30)
let s = String(describing: p)
print(s)
// Prints "(21, 30)"
The conversion of `p` to a string in the assignment to `s` uses the
`Point` type's `description` property.
get · iOS 14.0+
debugDescription
TypeScript
getDebugDescription($self: WidgetFamily): string
Swift declaration
var debugDescription: String { get }
A textual representation of this instance, suitable for debugging.
Calling this property directly is discouraged. Instead, convert an
instance of any type to a string by using the `String(reflecting:)`
initializer. This initializer works with any type, and uses the custom
`debugDescription` property for types that conform to
`CustomDebugStringConvertible`:
struct Point: CustomDebugStringConvertible {
let x: Int, y: Int
var debugDescription: String {
return "(\(x), \(y))"
}
}
let p = Point(x: 21, y: 30)
let s = String(reflecting: p)
print(s)
// Prints "(21, 30)"
The conversion of `p` to a string in the assignment to `s` uses the
`Point` type's `debugDescription` property.
init · iOS 14.0+
init
TypeScript
init(rawValue: number): (WidgetFamily) | null
Swift declaration
init?(rawValue: Int)
Creates a new instance with the specified raw value.
If there is no value of the type that corresponds with the specified raw
value, this initializer returns `nil`. For example:
enum PaperSize: String {
case A4, A5, Letter, Legal
}
print(PaperSize(rawValue: "Legal"))
// Prints "Optional(PaperSize.Legal)"
print(PaperSize(rawValue: "Tabloid"))
// Prints "nil"
- Parameter rawValue: The raw value to use for the new instance.
get · iOS 14.0+
rawValue
TypeScript
getRawValue($self: WidgetFamily): number
Swift declaration
var rawValue: Int { get }
The corresponding value of the raw type.
A new instance initialized with `rawValue` will be equivalent to this
instance. For example:
enum PaperSize: String {
case A4, A5, Letter, Legal
}
let selectedSize = PaperSize.Letter
print(selectedSize.rawValue)
// Prints "Letter"
print(selectedSize == PaperSize(rawValue: selectedSize.rawValue)!)
// Prints "true"
