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.
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.
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.
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.
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.