Android 12 widgets improvements

Android 12 (API level 31) revamps the existing Widgets API to improve the user and developer experience in the platform and launchers. Use this guide to learn how to ensure your widget is compatible with Android 12, and also as a reference for APIs for refreshing your existing widget.

Alt text

Ensure your widget is compatible with Android 12

Widgets in Android 12 have rounded corners. When an app widget is used on a device running Android 12 or higher, the launcher automatically identifies the widget's background and crops it to have rounded corners.

In this scenario, your widget may not display properly in either of the following conditions:

  • The widget contains content in the corners: This may cause some content in the corner area to be cropped.

  • The widget uses a background that is not susceptible to cropping. This includes a transparent background, empty views or layouts, or any other kind of special background not prone to cropping. The system may not be able to correctly identify the background to use.

If your widget will be affected by this change, we recommend refreshing it with rounded corners (as described in the following section) to ensure it displays properly.

Use the sample

To see all these APIs in action, check out our sample list widget.

Implement rounded corners

Android 12 introduces the system_app_widget_background_radius and system_app_widget_inner_radius system parameters to set the radii of your widget's rounded corners.

Tokyo weather widget
Figure 1: Rounded corners on a widget and a view inside the widget

1 Corner of the widget.

2 Corner of a view inside the widget.

For details, see Implement rounded corners.

Add device theming

Starting in Android 12, a widget can use the device theme colors for buttons, backgrounds, and other components, including light and dark themes. This enables smoother transitions and consistency across different widgets.

See Add device theming for more information.

Widget in light mode theme
Figure 2: Widget in light theme
Widgets in dark mode theme
Figure 3: Widget in dark theme

Make it easier to personalize widgets

If you specify a configuration activity with the configure attribute of appwidget-provider, the App Widget host launches that activity immediately after a user adds the widget to their home screen.

Android 12 adds new options to let you provide a better configuration experience for users. See Enable users to configure widgets for details.

Add new compound buttons

Android 12 adds new support for stateful behavior using the following existing components:

The widget is still stateless. Your app must store the state and register for state change events.

Figure 4: Example widget with checkboxes

For details, see Support for stateful behavior.

Use improved APIs for widget sizes and layouts

Starting in Android 12, you can can take advantage of more refined size attributes and more flexible layouts, by specifying additional widget sizing constraints and by providing responsive layouts and exact layouts.

See Provide flexible widget layouts for details.

Improve your app's widget picker experience

Android 12 enables you to improve the widget picker experience for your app by adding dynamic widget previews and widget descriptions. For details, see Add scalable widget previews to the widget picker and Add a description for your widget.

Enable smoother transitions

Starting in Android 12, launchers provide a smoother transition when a user launches your app from a widget. See Enable smoother transitions for details.

Use simplified RemoteViews collections

Android 12 adds the setRemoteAdapter(int viewId, RemoteViews.RemoteCollectionItems items) method, which lets your app pass along a collection directly when populating a ListView. Previously, when using a ListView, it was necessary to implement and declare a RemoteViewsService to return RemoteViewsFactory.

For details, see Use RemoteViews collections.

Use runtime modification of RemoteViews

Android 12 adds several RemoteViews methods that allow for runtime modification of RemoteViews attributes. See the RemoteViews API reference for the full list of added methods.

For details, see Use runtime modification of RemoteViews.