How to Add a Widget to Your Expo App (iOS and Android)

Adding a widget to your Expo app means building a native extension that runs entirely outside your JavaScript bundle. On iOS, a WidgetKit widget is a separate Swift target compiled into your app binary. It has no bridge to React Native, no access to your JS state, and cannot call any of your JavaScript at runtime. On Android, an App Widget is a BroadcastReceiver backed by a RemoteViews layout - again, a separate native component that the home screen OS renders directly, not something Expo's React Native runtime touches.

This is the single most important thing to understand before you start. Every tutorial that starts with 'install this package and import it in App.tsx' is describing a package that bridges widget display, not one that lets you write your widget in JavaScript. The widget itself is always native. What differs between approaches is how much of the native boilerplate is pre-written for you.

Before you write a line of widget code, decide how your widget will read data. The only supported path on both platforms is a shared storage layer your main app writes to and your widget reads from. On iOS this is an App Group - a container shared between your main app target and your widget extension, accessed via UserDefaults(suiteName: 'group.your.bundle.id'). On Android it is SharedPreferences with a named file your AppWidgetProvider reads directly.

Your Expo app writes the data the widget needs into that shared store whenever the relevant data changes - on every foreground session, after a network fetch, after a user action. The widget reads from it when the home screen OS asks it to render. There is no push or callback between them. If your app has not written to the store yet, the widget renders a placeholder or empty state.

The fastest path for an Expo managed workflow is react-native-widget-extension. Install it, configure it in app.json, and EAS Build handles the rest of the Xcode target setup. You write the widget in Swift inside a directory the package points to, and the config plugin adds the target, the App Group entitlement, and the required Info.plist entries to your build automatically without you opening Xcode.

Android App Widgets need three pieces: an AppWidgetProvider class (a BroadcastReceiver that handles update events), a RemoteViews XML layout defining the widget's look, and an appwidget-provider XML metadata file that tells Android the widget's dimensions, update frequency, and initial layout. All three get wired into your AndroidManifest.xml via a config plugin.

In an Expo managed workflow, you write a local config plugin that copies the Kotlin file, the two XML files, and the manifest entries into the native project at build time. This is a few dozen lines of JavaScript that Expo's config plugin API makes straightforward. Claude Code can write the entire plugin once you describe the three native files you want to add.

Once the native widget can read from shared storage, you need your React Native app to write there. On iOS the most reliable package for this is react-native-shared-group-preferences, which exposes a setItem / getItem API scoped to an App Group. On Android, react-native-shared-preferences or a simple native module wrapping SharedPreferences both work. Write to the shared store in your app at the points where the underlying data changes - after a successful API call, after a user action, when the app comes to foreground.

On iOS you can also trigger a widget timeline reload from your app using WidgetKit's reloadAllTimelines. This forces the widget to re-read the store and re-render immediately rather than waiting for the OS to schedule the next update. The package react-native-widget-extension exposes this as a reloadAllTimelines() call you can trigger from JavaScript. Call it right after you write new data to the App Group.

The mechanical parts of this - the Swift widget file, the Kotlin provider, the two Android XML files, the config plugin JavaScript, the shared store reads and writes - are all things Claude Code writes well once you give it the data model and a description of what the widget should show. Prompt it with your data shape and a plain description of the widget UI, and it produces a working draft you can review and adjust.

What Claude Code cannot decide is what your widget should actually show and how often it should update. A widget that displays stale or empty data because the app never wrote to the shared store looks broken even if every line of code is correct. The design decisions - which piece of data earns a place on someone's home screen, and when it gets written - are the ones that make a widget worth adding at all.

Add an iOS widget via react-native-widget-extension: enable an App Group in your Apple Developer account, write a small Swift WidgetKit target, and let the config plugin handle the Xcode wiring in EAS Build. Add an Android App Widget via a local config plugin: write the Kotlin provider, the RemoteViews layout XML, and the appwidget-provider metadata, then copy them into the native project at build time. In both cases the data bridge is shared storage your main app writes and your widget reads. Claude Code writes all the native boilerplate once you describe the data and the display - your job is to pick what is worth showing on someone's home screen.