Countdown widget
A countdown to a date that keeps ticking on device between pushes. Add a start date and it fills a progress bar on its own.
This section describes a feature in an app update that's pending App Store review. It unlocks here automatically once the update is live.
The countdown template renders the time remaining until a date. WidgetKit redraws the
number itself, so one push sets the target and the widget stays correct for as long as it is
pinned — you only send another update when the target moves.
Fields
| Field | Type | Notes |
|---|---|---|
template | string | Required. Must be "countdown" |
end_date | string | Required. RFC 3339 timestamp of the target. Must be after 2000-01-01 and no more than 366 days in the future. A date already in the past counts up instead of down |
start_date | string | RFC 3339 timestamp the countdown started from. Must be strictly before end_date. Adds a progress bar that advances on device |
expired_text | string | Shown in place of the countdown once end_date passes. Max 64 characters. Absent means the widget keeps counting, showing time elapsed since the target |
label, subtitle, icon, accent_color, background_color, text_color | string | Shared content fields — see the API reference |
Example: certificate renewal
{
"content": {
"template": "countdown",
"end_date": "2027-05-10T16:13:00Z",
"start_date": "2027-05-10T13:00:00Z",
"expired_text": "Renewing",
"label": "Cert renewal",
"subtitle": "api.pushward.app",
"icon": "lock.shield.fill",
"accent_color": "indigo"
}
}Behavior
With only end_date the widget is a bare countdown. Add start_date and it
also draws a bar that fills from the start to the target, advancing between pushes without any
further requests — the widget knows both ends of the window, so it can interpolate. That makes the
template cheap to drive: a maintenance window, a lease expiry, or a release date costs one PATCH
when it is scheduled and one when it changes.
After the target passes, expired_text takes over if you set it ("Renewing", "Out now", "Overdue"). If you did not, the widget flips to counting the
time elapsed since end_date, which is the right default for a deadline you want to
keep staring at.
Dates are bounded on both sides: anything before 2000-01-01 is rejected outright (it catches milliseconds accidentally sent as seconds, which land in 1970), and anything more than 366 days ahead is rejected too. The bounds are re-checked on every PATCH against the merged content, so a widget whose end_date has aged into the past stays patchable.
Pick a target and watch it tick on the playground before wiring it to a real schedule.