Widget
Root widget container
The root of the widget tree. Build one with new Widget({...}) and hand it to Script.setWidget(). Widget.currentFamily and Widget.parameter let the layout adapt. The tap action is configured on the Home Screen, not here. A Link node takes priority inside its own area; tapping anywhere else runs the configured action.
Properties
currentFamilyWidgetFamily ›The current widget family: 'small', 'medium', 'large', etc.
parameterStringThe text typed into the widget's Parameter field, or passed as Parameter from Shortcuts. One free-text value per widget instance, so the same script on three widgets can show three different things. Null when unset. From Shortcuts this is the same string as Script.input.text.
sizeAnyThe widget's real point size.
Methods
Widget(config?)WidgetNodeThe root of the widget tree.
- config Any
- child WidgetNode | fn(date: DateTime) -> WidgetNode
What the widget draws. With a timeline, a function called once per moment with that moment as a DateTime, returning what to draw then.
- supportedFamilies [WidgetFamily]
Which sizes this script offers. Every family by default.
- refreshInterval Duration
How often to ask for a redraw. iOS decides whether to grant it; five minutes is the floor.
- timeline Any
States drawn ahead, shown by iOS at their times without rerunning the script: { every: Duration, count } for regular steps of at least a minute (count defaults to 60), or { at: [dates] }. Needs child to be a function. Up to 180 states.
- every Duration
Time between states, at least one minute. The first state falls on the current boundary, 09:07:00 rather than 09:07:23.
- count Number
How many states. Defaults to 60.
- at [DateTime | Date | number]
Exact moments instead of a regular step, e.g. a countdown that only changes at 1 hour, 10 minutes and 1 minute left.
- every Duration
- backgroundColor Color
A flat background.
- backgroundGradient LinearGradient
A gradient background. Wins over backgroundColor.
- padding EdgeInsets
Space between the edge and the child.
- child WidgetNode | fn(date: DateTime) -> WidgetNode
Widget.requestReload()Request a widget timeline reload. Tells WidgetKit to re-run the script and refresh the widget display.
Examples
Adaptive widget
const family = Widget.currentFamily;
const isSmall = family === "small";
const content = isSmall
? Text("Compact")
: Column({ children: [
Text("Expanded"),
Text("More details here")
]});
const widget = new Widget({
backgroundColor: Color.hex("#1a1a2e"),
padding: EdgeInsets.all(16),
child: content
});
Script.setWidget(widget);A clock that turns over every minute
Script.setWidget(new Widget({
timeline: { every: Duration.minutes(1), count: 60 },
child: function (date) {
return Text(date.format("HH:mm"), { font: Font.system(44, FontWeight.bold) });
},
}));