Widget Quality Tiers

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 can impact user engagement with your app content and features. There are three main tiers of widget quality:

  • Tier 3: Low Quality - don't meet the minimum quality bar and don't provide a great user experience.
  • Tier 2: Quality Standard - is helpful, usable, and provides a quality experience.
  • Tier 1: Differentiated - are exemplary widgets offering hero experiences that are personalized, and help users create unique and productive homescreens.

Tier 3: Low Quality

A widget is deemed low quality if it does not meet standard layout, color, discovery, and content criteria. For more information on building a best practice, high-quality widget, refer to the following guidelines.

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. Widget can be resized to at least one of the following sizes : 2x2, 4x2 (launcher grid cells). For more information, see Sizing guidelines.
    • 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 or 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).

Do

Provide touch targets at 48x48 dp.

Don't

Make touch targets too small.

Color

  • Widget text and icon buttons must have sufficient contrast ratios to meet accessibility requirements (excludes thumbnails and images).

Do

Ensure sufficient color contrast.

Don't

Use colors with insufficient color contrast.

Discovery

  • Widget must have accurate previews in the Widget picker. This can be set with previewImage and previewLayout in the AppWidgetProviderInfo XML, or with Generated Previews.

    • Widget preview looks consistent with functionality that is offered when added to the homescreen.
    Video 1: Widget with inaccurate preview.

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 let users 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 or provide a call to action, when the widget is installed but the user is not yet logged in.
discovery_tier2
Figure 2. Widget with valuable empty state.
discovery_tier2
Figure 3. Widget with refresh button.

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

Do

Have widget expand to all 4 edges of the grid bounds.

Don't

Make a custom size that doesn't fill the grid bounds.

  • 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:
      • You want to provide deep links to certain app functions like search.
      • You want to apply an app branding icon which doubles as a consistent link back to the app on tap.
      • 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

Do

Provide a header that meets widget specs.

Don't

Use custom specs for size and titles.

Color

Widgets displaying dynamic theming
Figure 4. Widgets with wallpaper dynamic colors and branded theme colors.

Discovery

Widgets with generic and user-content previews
Figure 5. Widgets with generic preview content and user-content preview content.
  • 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. For example, the app can't have multiple widgets named the same thing.

Do

Include a unique succinct description.

Don't

Provide a generic description.

System Coherence

  • Rectangular widgets must use the corner radius provided by system (OEM specific)

Do

Use system corner radius.

Don't

Set custom corner radius.
Widgets with different loading states
Figure 6. Widgets with loading indicator and a custom loading state.
  • 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 the Android Widget Templates, and developers refer to Layout code samples in our Platform Samples & the Layouts developer guide.