Widget states and built-in UI components

Widget states

When a widget is displayed on the Widgets Board, there are several different states that it can be in, depending on the current state of the Widgets Board and your app, such as when the widget is loading, when the widget is in an error state, or when the user has customized the widgets layout. Some states are designed and implemented by your app while others are built into the Widgets host. This section shows and describes each widget state. Keep in mind that widgets support both light and dark themes, so the built-in states and the states you customize may both look different depending on the current theme.

Default state

The default state is what the widget looks like when it is running normally. This is the primary user experience for your widget. You design the layout for your widget's default state. Although the UI of your widget's default state may change in response to user configuration, your widget's default state should be fully implemented and should not be empty before user configuration. If your widget requires the user to sign-in, you may want to implement a signed-out state, described below. For design guidance for creating the default state for your widget, see Widget design fundamentals.

DO

• When in the default, active state a widget should feel personal and connected to user.
• Widgets should show engaging content that brings the user value in the current moment.
• Give the user the ability to start interacting with widget right away.
• Provide a UI that reflects the UI of your app, while staying within the design constraints for widgets, in order to maximize consistency and to lessen the learning curve.
• Consider using the user’s location to pre-populate the data for content like sports and suggested calendars to add instead of generic data.
• Allow ample breathing space between elements.

DON’T

• Use your widget for generic commercial offers. The content should reflect the user's desires and intent.
• Avoid busy, complex layouts.

Aim for comfortable information density and healthy negative space within each widget size to help with the glance and go model. If you have a lot of information to include, consider the next size up to show more content. Also consider how difficult/easy the content will be for a user to glance and consume.

Consider adding moments of surprise + delight to your widgets to elevate the experience. For example, for the Family or Calendar widgets you could highlight a child’s birthday via different visual treatments.

This is the state with the most design flexibility. Use the guidelines in this articles as well as Widget principles, Widget design fundamentals, and Widget interaction design guidance to design how you want to layout your content.

Signed-out state (for widgets that require authentication)

Some widget scenarios may require that the user must sign in or perform other actions to be able to see personalized widget content. When the user is not signed in, you should consider presenting non-personalized content.

If that content is a placeholder rather than personalized or actionable information, set WidgetUpdateRequestOptions.IsPlaceholderContent to true. The host may prioritize widgets with customized content over widgets with placeholder content. Use the widget host properties to account for interaction restrictions when the user context isn't authenticated.

Error state - system provided

If for some reason, the Widgets Board can't retrieve the layout or data for a widget, it will display an error state. Windows will show the widget header with an error message and a reload button. This message will look the same for every widget.

If there is cached content available to be displayed, the widget header will show when data was last refreshed in the following format:

1. The number of minutes if less than an hour
2. Rounding to the nearest hour if over an hour

Long widget partner names will get truncated while showing a cached message at 15 characters max.

Customization state

Starting with Windows App SDK 1.4, widgets can provide a customization template that provides controls for the user to customize the widget's appearance or the data displayed by the widget. The customization UI is defined in a JSON template.

Built-in widget UI components

The widget host supplies UI such as the context menu and default header. Providers don't control all host UI, but they can declare customization support and override the header where the host supports it.

Context menu (system provided)

The context menu opens from the widget's three-dot button. Users can choose a supported size, unpin the widget, and open its customization UI if the provider declares IsCustomizable in the manifest. For implementation details, see Implementing widget customization.

Attribution area

By default, the Widgets Board renders the attribution area from the widget name and icon in the package manifest. The default title bar can navigate to the URI specified by AdditionalInfoUri in the manifest. Where header customization is supported, a provider can override the header text and icon, or set header to null so content can extend into that region. Content extended into an empty header isn't clickable; this restriction doesn't disable the default title bar's AdditionalInfoUri navigation. See Customize the widget header area and Widget provider package manifest XML format.