React Native Android Widgets: Native Host, Shared Data and Update Limits

Create the Android pieces explicitly

For an illustrative saved-task widget, start in the Android app module. Add a small layout such as res/layout/task_widget.xml, metadata such as res/xml/task_widget_info.xml, and a Kotlin TaskWidgetProvider extending AppWidgetProvider. Register the provider's receiver and its android.appwidget.provider metadata in the manifest. The XML resource links the initial layout to the widget's dimensions and resizing behavior. Follow the Android widget setup for the manifest and resource contract.

The provider uses supported RemoteViews operations rather than mounting a React component. A fragment of its rendering method can look like this; the resource IDs are names you must define in the native layout, and taskTitle comes from your persisted snapshot.

val views = RemoteViews(context.packageName, R.layout.task_widget)
views.setTextViewText(R.id.task_title, taskTitle)
appWidgetManager.updateAppWidget(appWidgetId, views)

This fragment updates a single widget instance. Iterate the IDs passed to onUpdate when refreshing multiple instances, and read each instance's configuration separately. The AppWidgetManager API provides the update and instance lookup operations. Keeping the ID explicit prevents one user's chosen list from accidentally replacing every widget with the same content.

Bridge a small persisted snapshot

Define the data boundary before writing JavaScript. For this task example, a useful snapshot contains a list identifier, one display title, a completion count and an update timestamp. A React Native native module can validate that shape, write it to storage accessible to the native provider, then request a widget refresh. The module must resolve its JavaScript promise only after the write succeeds, so the screen cannot report success while the widget still reads an old snapshot.

Choose a module implementation compatible with the project's React Native architecture. The native-platform documentation distinguishes native modules from native UI components and covers migration from older APIs. The widget provider does not need a Fabric view merely to read a stored task title. Avoid solving this by launching the entire React Native runtime whenever the launcher asks for an update.

Persist a safe empty state too. If the user signs out, clear account-bound text and render a message such as “Open the app to choose a list.” Do not leave yesterday's private task on the home screen until the next scheduled refresh. For multiple accounts, store the active account context with the snapshot and reject a snapshot whose account no longer matches the application's selected identity.

Test a widget with no live React screen

Add two widget instances and choose different lists. Save a new title in the app, return to the launcher and check that the correct instance updates. Then stop the app process through the development tools without clearing its data. Trigger a normal widget update and confirm that the title can still be rendered from storage. A design that only works while the original JavaScript screen remains open has missed the native lifecycle requirement.

Resize each instance, change the device's font scale and switch between light and dark launcher themes. A long title should remain understandable within the allocated cells, and the tap target should open the correct destination. If the destination needs authentication, recheck the session inside the activity rather than treating a widget click as proof of login. Use an explicit pending intent with the correct mutability flags for the supported Android versions.

Finally, simulate a network outage while the last saved snapshot exists. Keep that snapshot with a visible update time, or show a deliberate unavailable state according to the product's requirements. Widget scheduling and background limits are unsuitable for a promised continuously live feed. Measure the experience on a device and launcher you support; an APK inspection can confirm packaged declarations, but it cannot demonstrate these launcher interactions.