capacitor-widget-bridge

A Capacitor plugin to interact with WidgetKit (iOS) and App Widgets (Android). Allows your Capacitor app to store data in shared user defaults (iOS) or shared preferences (Android), and update timeline widgets on both platforms.

Demo

Install

npm install capacitor-widget-bridge
npx cap sync

Credits

Inspired by 0xn33t, who created the original iOS WidgetKit bridge.
This plugin extends it with Android support and multi-platform improvements. Thank you for the groundwork!

Platform Setup

iOS

1. Enable App Groups in your Xcode project.
2. Add your App Group ID (e.g., group.your.bundle.id) to UserDefaultsOptions.group.
3. Create a Widget Extension using SwiftUI and define your widgets.
4. Use UserDefaults(suiteName:) with your group ID in the widget.
5. Call WidgetBridgePlugin.reloadAllTimelines() or reloadTimelines(...) after saving data.

Android

1. Create one or more AppWidgetProvider classes (i.e., your widgets).
2. Declare them in your AndroidManifest.xml with <receiver ... />.
3. In your app’s JS code, register the widget classes:

   if (Capacitor.getPlatform() === 'android') {
     WidgetBridgePlugin.setRegisteredWidgets({
       widgets: ['com.example.plugin.MyWidget'],
     });
   }

4. Call WidgetBridgePlugin.setItem(...) and then reloadAllTimelines() or reloadTimelines(...) to trigger updates.
5. Use SharedPreferences in your widget code to read the data, using the same key/group as in JS.

API

• getItem(...)
• setItem(...)
• removeItem(...)
• reloadAllTimelines()
• reloadTimelines(...)
• setRegisteredWidgets(...)
• getCurrentConfigurations()
• Interfaces

getItem(...)

getItem(options: UserDefaultsOptions) => Promise<DataResults<any>>

Returns the value from the user’s defaults/shared preferences associated with the specified key.

• iOS: Uses UserDefaults with app group support.
• Android: Uses SharedPreferences with private app storage.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | UserDefaultsOptions |

Returns: Promise<DataResults<any>>

Since: 7.0.0

setItem(...)

setItem(options: UserDefaultsOptions) => Promise<DataResults<boolean>>

Sets the value to the user’s defaults/shared preferences associated with the specified key.

• iOS: Uses UserDefaults with app group support.
• Android: Uses SharedPreferences with private app storage.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | UserDefaultsOptions |

Returns: Promise<DataResults<boolean>>

Since: 7.0.0

removeItem(...)

removeItem(options: UserDefaultsOptions) => Promise<DataResults<boolean>>

Removes the value from the user’s defaults/shared preferences associated with the specified key.

• iOS: Uses UserDefaults.
• Android: Uses SharedPreferences.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | UserDefaultsOptions |

Returns: Promise<DataResults<boolean>>

Since: 7.0.0

reloadAllTimelines()

reloadAllTimelines() => Promise<DataResults<boolean>>

Reloads timelines for all configured widgets in the app.

• iOS: Triggers WidgetCenter reload.
• Android: No-op (not applicable).

Returns: Promise<DataResults<boolean>>

Since: 7.0.0

reloadTimelines(...)

reloadTimelines(options: TimelinesOptions) => Promise<DataResults<boolean>>

Reloads timelines for all widgets of a specified kind.

• iOS: Triggers reload of specific widget kind.
• Android: No-op (not applicable).

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | TimelinesOptions |

Returns: Promise<DataResults<boolean>>

Since: 7.0.0

setRegisteredWidgets(...)

setRegisteredWidgets(options: RegisteredWidgetsOptions) => Promise<DataResults<boolean>>

Registers widget provider class names for dynamic timeline updates on Android.

• iOS: No-op.
• Android: Used to register widget classes for reloadAllTimelines.

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | RegisteredWidgetsOptions |

Returns: Promise<DataResults<boolean>>

Since: 7.0.0

getCurrentConfigurations()

getCurrentConfigurations() => Promise<DataResults<any>>

Retrieves current widget configurations.

• iOS: Returns active widget info via WidgetCenter.
• Android: Not supported (returns empty or dummy data).

Returns: Promise<DataResults<any>>

Since: 7.0.0

Interfaces

DataResults

| Prop | Type | Description | Since | | ------------- | -------------- | --------------------------------------- | ----- | | results | T | Holds response results from native code | 7.0.0 |

UserDefaultsOptions

| Prop | Type | Description | Since | | ----------- | ------------------- | --------------------------------------------------------------------- | ----- | | key | string | The key whose value to retrieve from storage. | 7.0.0 | | group | string | User defaults database name which holds and organizes key/value pairs | 7.0.0 | | value | string | The value to set in storage with the associated key | 7.0.0 |

TimelinesOptions

| Prop | Type | Description | Since | | ------------ | ------------------- | -------------------------------------------------------------------------------------------------------------- | ----- | | ofKind | string | A string that identifies the widget and matches the value you used when you created the widget’s configuration | 7.0.0 |

RegisteredWidgetsOptions

| Prop | Type | Description | Since | | ------------- | --------------------- | --------------------------------------------------------------- | ----- | | widgets | string[] | Fully qualified class names of widgets to register for updates. | 7.0.0 |