Android 12 (API level 31) revamps the existing[Widgets API](https://developer.android.com/guide/topics/appwidgets/overview)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](https://developer.android.com/static/images/appwidgets/widget-intro.png "Widget examples")

## 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.
| **Caution:** The dimensions of rounded corners may vary across devices because the size of the corner radius is controllable by both device manufacturers (up to 16dp) and third-party launchers. We recommend refreshing the widget to help avoid unsatisfactory results.

### Use the sample

To see all these APIs in action, check out our[sample list widget](https://github.com/android/user-interface-samples/tree/main/AppWidget).

## Implement rounded corners

| **Note:** This guidance may be outdated. Refer to[Implement rounded corners](https://developer.android.com/guide/topics/appwidgets#rounded-corner)for the latest guidance.

Android 12 introduces the[`system_app_widget_background_radius`](https://developer.android.com/reference/android/R.dimen#system_app_widget_background_radius)and[`system_app_widget_inner_radius`](https://developer.android.com/reference/android/R.dimen#system_app_widget_inner_radius)system parameters to set the radii of your widget's rounded corners.
![Tokyo weather widget](https://developer.android.com/static/images/appwidgets/widget-weather.png)**Figure 1:**Rounded corners on a widget and a view inside the widget

1Corner of the widget.

2Corner of a view inside the widget.

For details, see[Implement rounded corners](https://developer.android.com/guide/topics/appwidgets#rounded-corner).

## 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](https://developer.android.com/guide/topics/appwidgets/enhance#dynamic-colors)for more information.
![Widget in light mode theme](https://developer.android.com/static/images/appwidgets/example-lightmode.png)**Figure 2:**Widget in light theme![Widgets in dark mode theme](https://developer.android.com/static/images/appwidgets/example-darkmode.png)**Figure 3:**Widget in dark theme

<br />

## Make it easier to personalize widgets

If you specify a configuration activity with the[`configure`](https://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo#configure)attribute of[`appwidget-provider`](https://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo), 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](https://developer.android.com/guide/topics/appwidgets/configuration)for details.

## Add new compound buttons

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

- [`CheckBox`](https://developer.android.com/reference/kotlin/android/widget/CheckBox)

- [`Switch`](https://developer.android.com/reference/android/widget/Switch)

- [`RadioButton`](https://developer.android.com/reference/android/widget/RadioButton)

The widget is still stateless. Your app must store the state and register for state change events.
![](https://developer.android.com/static/images/appwidgets/home.png)**Figure 4:**Example widget with checkboxes

For details, see[Support for stateful behavior](https://developer.android.com/guide/topics/appwidgets#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](https://developer.android.com/guide/topics/appwidgets/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](https://developer.android.com/guide/topics/appwidgets/enhance#add-scalable-widget-previews)and[Add a description for your widget](https://developer.android.com/guide/topics/appwidgets/enhance#add-widget-description).

## 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](https://developer.android.com/guide/topics/appwidgets/enhance#enable-smoother-transitions)for details.

## Use simplified`RemoteViews`collections

Android 12 adds the[`setRemoteAdapter(int viewId, RemoteViews.RemoteCollectionItems items)`](https://developer.android.com/reference/android/widget/RemoteViews#setRemoteAdapter(int,%20android.widget.RemoteViews.RemoteCollectionItems))method, which lets your app pass along a collection directly when populating a[`ListView`](https://developer.android.com/reference/android/widget/ListView). Previously, when using a`ListView`, it was necessary to implement and declare a`RemoteViewsService`to return[`RemoteViewsFactory`](https://developer.android.com/reference/android/widget/RemoteViewsService.RemoteViewsFactory).

For details, see[Use`RemoteViews`collections](https://developer.android.com/guide/topics/appwidgets/collections#use-remote-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`](https://developer.android.com/guide/topics/appwidgets/enhance#use-runtime-mod-of-remoteviews).