Fitness App Widgets and Watch Complications

A widget is the cheapest recurring impression a fitness app can own, and the easiest one to poison. It sits on a surface the user already looks at, it costs them nothing, and no permission dialog can switch it off. It can also display yesterday's number for a week straight, which is worse than not existing at all.

WidgetKit covers more than the Home Screen#

Apple describes WidgetKit as a way to "extend the reach of your app by creating widgets, watch complications, Live Activities, and controls," and to make "your app's content available in contexts outside the app" as "an ecosystem of glanceable, up-to-date experiences."

The surfaces Apple documents are broader than most teams build for: iPhone and iPad Today View, Home Screen and Lock Screen; the Mac desktop and Notification Center; the Apple Watch Smart Stack; Apple Vision Pro; and CarPlay. Watch complications appear on the watch face, and Apple documents up to three complications in the Smart Stack. Controls appear in Control Center, on the Lock Screen and on the Action button.

For a fitness app the watch face is usually the most valuable address on that list, because it is glanced at more often than any phone screen and it is on the device closest to the activity.

The timeline model, and the one thing it does not cover#

Apple documents the update mechanism directly: "Widgets and watch complications use a special mechanism to update their content: You create a timeline of data updates and hand it to WidgetKit. WidgetKit then makes sure the widget or complication updates its content in an energy-efficient way." Apple also documents that widgets can be updated via APNs.

The mental shift is that you are not rendering a widget on demand; you are describing what it should show at a series of future moments and handing that description to the system. Fitness content fits this better than it first appears — a rest day is predictable, a streak's next deadline is a known timestamp, and a weekly progress bar changes on a schedule you already own.

We are deliberately not quoting a refresh budget or a number of daily reloads. Those figures circulate widely, we could not verify one against Apple's documentation this session, and designing against an unverified quota is how you end up with a widget that is wrong in production and right on your desk. Assume you may be refreshed less often than you hoped and degrade honestly when that happens.

Live Activities are the exception inside WidgetKit's own family: Apple documents that they do not use the timeline mechanism, and they are driven from the app or by ActivityKit push notifications instead. See Live Activities for workout tracking.

Android: Jetpack Glance and Wear OS tiles#

Google describes Jetpack Glance as "a framework built on top of the Jetpack Compose runtime that lets you develop and design app widgets using Kotlin APIs," and defines the target artifact: "app widgets are miniature application views that can be embedded in other applications and receive periodic updates."

There is one caution in Google's documentation that regularly surprises Compose teams. Glance "requires Compose to be enabled and depends on Runtime, Graphics, and Unit UI Compose layers, but it's not directly interoperable with other existing Jetpack Compose UI elements. Avoid mixing the two." In practice your widget's UI is a separate implementation from your app's UI even though both are Kotlin and both look like Compose. Budget for that instead of assuming you can lift a composable across. Google's Glance documentation also covers building Wear OS tiles.

What a fitness widget should show#

The design constraint is that a widget is read in roughly the time it takes to walk past it. One number and one piece of state is the entire budget.

The candidates that earn the space:

Last workout — what it was and when. This answers "did I train yesterday" without opening anything.

Streak state, expressed as a deadline rather than a count. "Today still counts" is actionable. A bare number is a trophy.

Weekly progress against the goal the user actually set, not a generic ring your product team likes.

The next scheduled session, if your app owns a plan. This is the only widget content that hands the user something to do rather than something to admire.

What not to show: motivational copy, anything that needs a sentence to explain, and any metric the user never asked to track.

Staleness is the whole engineering problem#

A widget displaying yesterday's number as though it were today's is worse than no widget, because the user cannot tell the difference. There is no loading spinner in a glance.

Three habits, offered as judgement rather than platform rule:

Show the "as of" state, not just the value. A timestamp or a relative marker converts a wrong number into an honest old one.

Build the timeline around known future transitions. Midnight in the user's own time zone is the big one for anything streak- or day-shaped, and it is genuinely hard — see time zones and day boundaries and the day boundaries reference.

Push when something real happens instead of relying on scheduled refresh alone. A completed workout is precisely the event that should reach the widget promptly.

Then test the empty states, because a brand-new user, a user with no data since a reinstall, and a user whose sync is silently broken all render the same code path, and that path is usually the one nobody opened.