Widgets are a critical component for customizing a user's homescreen. They can often help users achieve a critical user journey for an app with a single tap, or provide a quick summary of an app's most important pieces of data. They can also be customized to fit the needs of the user and tailored to individual preferences.
The quality of a widget determines how likely a user engages with it. There are three main categories of widget quality:
- Tier 3: Low Quality - under performs, is stale, and does not provide a great user experience
- Tier 2: Quality Standard - serves all basic needs and provides a satisfactory experience
- Tier 1: Differentiated - exceeds the basic expectations of the user and provides the optimal user experience
Tier 3: Low Quality
A widget is deemed low quality if it does not meet standard layout, color, discovery, and content criteria. Refer to the guidelines below for more information on exceeding the low quality tier.
Tier 2 - Quality Standard
To be considered good quality, the widget meets all of the following Layout, Color, Discovery and Content criteria:
Layout
- Widget must fill the bounds
set by the launcher grid when dropped on the homescreen.
If it does not meet the specifications below, it is categorized as tier 3, low
quality.
- Widget must align properly to other home screen elements on the vertical or horizontal axis, and does not occupy unnecessary space
- Widget must touch at least two opposing edges of the grid. In other words, widgets don't need to be rectangular, they can have custom shapes, as long as the edges of the shape touch at least two edges of the grid.
- If resizable, widgets must have an appropriate min/max size, which can be set
with minWidth, minHeight, maxResizeWidth, and maxResizeHeight in the
AppWidgetProviderInfo XML
- Max size should be set if resizing the widget only adds blank space
- Min size should be set based on the minimum size your widget still offers value and meets touch target requirements (48x48)
Color
- Widget text and icon buttons must have sufficient contrast ratios to meet accessibility requirements (excludes thumbnails and images)
Discovery
- Widget must have accurate previews in the Widget picker (static asset ok).
This can be set with previewImage and previewLayout in the
AppWidgetProviderInfo XML,
or with Generated Previews
- Widget preview looks consistent with functionality that will be offered when added to the homescreen
Content
- Widget content must not be consistently stale or untimely
- Widget must update after user completes an action from the widget
- Widget must update after user completes a related action from within the app
- Widget must allow users to manually refresh content, if there is an expectation the data refreshes more frequently than the UI
- Widget UI must be functional or content is cropped
- Widget zero and empty states must be intentional and must show the value of the widget and/or provide a call to action, when the widget is installed but the user is not yet logged in
Tier 1 - Differentiated
The best widgets meet all of the Tier 2 criteria and all of the following Layout, Color, Discovery and System Coherence criteria
Layout
- Widget fills the bounds and aligns properly to other home screen elements on
the vertical or horizontal axis, and does not occupy unnecessary space
- All shapes MUST hit all four edges of the bounds of the grid
Widget supports a preferred size
- Widget can be resized to at least one of the following sizes : 2x2, 4x2
Widget header is used and applied consistently
- Recommend use of header if:
- Widget contains scrolling content (list, grid, etc)
- Header content provides helpful context (name of to-do list)
- Header is optional when:
- Widget is a full bleed image (Photos)
- Space is limited (< 2 rows tall)
- When header content is redundant.
- If using a header, meet our spec:
- Icon, Title, Actions.
- Icon is always present
- Title appears when there is sufficient space
- Actions based on widget context.
- Height 48dp, Padding, 14dp
- Icon, Title, Actions.
- Recommend use of header if:
Color
- Widget supports color theming based on a device or app context.
- Dynamic color is an example of device context theming
- Local color extraction is an example of app content based theming
- Semantic color is an example of app content based theming.
- Widget supports Light and Dark mode palettes
Discovery
- Preview includes user-content and/or applies system theme (Generated Previews api or previewLayout in the AppWidgetProviderInfo XML)
- Widget has a name or description that helps users understand the value
of the widget
- The name is less than 50 characters long
- The name and description are unique within the app (e.g. the app can't have multiple widgets named the same thing)
System Coherence
- Rectangular widgets must use the corner radius provided by system (OEM specific)
- Shows a loading state with a progress
indicator
(within an
initialLayout
with themed color or branded equivalent)
- Uses system configuration instead of a custom widget settings entrypoint
- Uses system launch transition when entering/exiting app to widget
Remember the tips offered in this guide when creating your widget. You want to provide the best quality and a great user experience. Many quality bars can be met with Canonical Layouts. To learn more about quality bars, designers refer to Android Widget Templates, and developers refer to Layout code samples in our Platform Samples & the Layouts developer guide.