@capgo/capacitor-widget-kit

Create Home Screen WidgetKit, ActivityKit, and Android widget experiences from Capacitor without forcing one rendering model.

Demo

Widget Screenshots

iOS Lock Screen / Live Activity

iOS Dynamic Island

The plugin has two implementation paths:

• SVG template widgets: store Home Screen, Lock Screen, Dynamic Island, and Android layouts with optional named frames, hotspots, declarative state patches, pause/resume timers, and interaction events. Use this when your widget can be driven by resolved SVG output.
• Full-native widget sessions: store shared JSON state for native widget code and queue app-to-widget or widget-to-app messages. Use this when you want to render the widget fully in Swift/Kotlin/Java but still need Capacitor to start, stop, sync, or process async work.

The included workout flow is only an example helper built on top of the generic SVG abstraction.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-widget-kit` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add file:../capacitor-widget-kit
bunx cap sync ios
bunx cap sync android

iOS Requirements

• Add a Widget Extension target for Home Screen / SpringBoard widgets.
• iOS 17+ is recommended for interactive Home Screen widget and Live Activity buttons.
• Add NSSupportsLiveActivities to the app Info.plist when using ActivityKit.
• Add the same App Group to the app target and the widget extension target.
• Set CapgoWidgetKitAppGroup in both Info.plist files to the shared App Group identifier.

Example App Group:

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

Native Widget Code

The plugin ships the native pieces a widget extension or Android widget can use:

• CapgoTemplateActivityAttributes for the iOS Live Activity bridge
• CapgoTemplateActionIntent for interactive iOS template buttons
• CapgoTemplateWidgetTimelineProvider and CapgoTemplateHomeWidgetView for real iOS Home Screen / SpringBoard widgets backed by WidgetKit timelines
• CapgoTemplateWidgetBridge to load a stored SVG activity and resolve one surface into svg + width/height + frameId + hotspots + metadata
• CapgoTemplateSurfaceView, CapgoTemplateWidgetSurface, and CapgoTemplateLatestWidgetSurface to place a rendered SVG view under native hotspot buttons in SwiftUI
• CapgoNativeWidgetBridge to load full-native widget sessions and exchange async messages without using SVG templates
• CapgoTemplateActionReceiver and CapgoTemplateWidgetBridge for Android template widgets

In your iOS widget extension bundle:

import ActivityKit
import SwiftUI
import WidgetKit
import CapgoWidgetKitShared

@main
struct ExampleWidgetBundle: WidgetBundle {
    var body: some Widget {
        ExampleTemplateHomeWidget()

        if #available(iOS 16.2, *) {
            ExampleTemplateLiveActivityWidget()
        }
    }
}

struct ExampleTemplateHomeWidget: Widget {
    private let kind = "ExampleTemplateHomeWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: CapgoTemplateWidgetTimelineProvider()) { entry in
            CapgoTemplateHomeWidgetView(entry: entry) { layout in
                MySvgRenderer(svg: layout.svg)
            } placeholder: {
                Text("No active widget")
            }
        }
        .configurationDisplayName("Capgo Template")
        .description("Home Screen widget rendered from the shared Capgo SVG template store.")
        .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
    }
}

Use the SwiftUI surface helpers when a custom WidgetKit view should be designed from JS but rendered by native widget code:

CapgoTemplateLatestWidgetSurface {
    layout in
    MySvgRenderer(svg: layout.svg)
} placeholder: {
    Text("No active widget")
}

The helper positions CapgoTemplateActionIntent buttons over the resolved SVG hotspots on iOS 17+. See example-app/widget-extension/ExampleWidgetBundle.swift for a complete Home Screen widget and Live Activity scaffold.

SVG Template Usage

This mode is for Home Screen, Lock Screen, Dynamic Island, and Android widgets that can render resolved SVG. Hotspot actions can switch frames, mutate state, pause/play timers, and emit events for the app to process later.

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

const { activity } = await CapgoWidgetKit.startTemplateWidget({
  activityId: 'session-1',
  openUrl: 'widgetkitdemo://session/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'generic-session-card',
    timers: [{ id: 'rest', durationPath: 'state.restDurationMs' }],
    actions: [
      {
        id: 'next-frame',
        eventName: 'widget.frame.changed',
        frameMutations: [{ op: 'next', path: 'frame', surface: 'homeScreen' }],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        timerMutations: [{ op: 'toggle', timerId: 'rest' }],
      },
    ],
    layouts: {
      homeScreen: {
        width: 100,
        height: 40,
        frameIdPath: 'state.frame',
        frames: [
          {
            id: 'summary',
            hotspots: [{ id: 'switch', actionId: 'next-frame', x: 0, y: 0, width: 100, height: 40 }],
            svg: `<svg viewBox="0 0 100 40"><text x="6" y="20">{{state.title}}</text></svg>`,
          },
          {
            id: 'timer',
            hotspots: [{ id: 'pause-play', actionId: 'toggle-rest', x: 0, y: 0, width: 100, height: 40 }],
            svg: `<svg viewBox="0 0 100 40"><text x="6" y="20">{{timers.rest.remainingText}}</text></svg>`,
          },
        ],
      },
    },
  },
});

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

const pendingEvents = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

Full-Native Widget Usage

This mode is for widgets rendered in native code. The app keeps a shared session state for sync reads/writes, and messages cover async jobs that need a later response.

const { session } = await CapgoWidgetKit.startWidgetSession({
  widgetId: 'native-session-1',
  kind: 'workout-controls',
  state: { isRunning: true, selectedSetId: 'set-1' },
  metadata: { accent: '#00d69c' },
});

await CapgoWidgetKit.updateWidgetSession({
  widgetId: session.widgetId,
  merge: true,
  state: { isRunning: false },
});

const { message } = await CapgoWidgetKit.sendWidgetMessage({
  widgetId: session.widgetId,
  direction: 'widgetToApp',
  name: 'syncWorkoutSet',
  payload: { setId: 'set-1' },
  expectsResponse: true,
});

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  response: { synced: true },
});

await CapgoWidgetKit.stopWidgetSession({ widgetId: session.widgetId });

Example App

The example-app/ folder is a lightweight Vite demo for the generic template flow. It runs in the browser using the preview store and demonstrates:

• starting one SVG template widget for the Home Screen surface
• resolving the Home Screen surface
• running an action from the app and from a hotspot overlay
• reading the stored widget template back
• reading and acknowledging the event log
• ending the stored template

The workout helper is only used there as an example template factory.

API

areActivitiesSupported() => Promise<ActivitiesSupportedResult>

startTemplateActivity(options: StartTemplateActivityOptions) => Promise<StartTemplateActivityResult>

startTemplateWidget(options: StartTemplateWidgetOptions) => Promise<StartTemplateActivityResult>

updateTemplateActivity(options: UpdateTemplateActivityOptions) => Promise<TemplateActivityResult>

endTemplateActivity(options: EndTemplateActivityOptions) => Promise<void>

performTemplateAction(options: PerformTemplateActionOptions) => Promise<PerformTemplateActionResult>

getTemplateActivity(options: GetTemplateActivityOptions) => Promise<TemplateActivityResult>

listTemplateActivities() => Promise<ListTemplateActivitiesResult>

listTemplateEvents(options?: ListTemplateEventsOptions | undefined) => Promise<ListTemplateEventsResult>

acknowledgeTemplateEvents(options: AcknowledgeTemplateEventsOptions) => Promise<void>

startWidgetSession(options: StartWidgetSessionOptions) => Promise<StartWidgetSessionResult>

updateWidgetSession(options: UpdateWidgetSessionOptions) => Promise<WidgetSessionResult>

stopWidgetSession(options: StopWidgetSessionOptions) => Promise<void>

getWidgetSession(options: GetWidgetSessionOptions) => Promise<WidgetSessionResult>

listWidgetSessions() => Promise<ListWidgetSessionsResult>

sendWidgetMessage(options: SendWidgetMessageOptions) => Promise<SendWidgetMessageResult>

listWidgetMessages(options?: ListWidgetMessagesOptions | undefined) => Promise<ListWidgetMessagesResult>

acknowledgeWidgetMessages(options: AcknowledgeWidgetMessagesOptions) => Promise<void>

completeWidgetMessage(options: CompleteWidgetMessageOptions) => Promise<WidgetMessageResult>

reloadWidgets(options?: ReloadWidgetsOptions | undefined) => Promise<void>

getPluginVersion() => Promise<PluginVersionResult>