# react-native-live-widgets — Full AI Reference Manual (llms-full.txt) > Comprehensive reference guide for Large Language Models (LLMs) and autonomous AI coding agents implementing Live Activities, Dynamic Island, and Home Screen Widgets in React Native and Expo. --- ## 1. High-Level Architecture `react-native-live-widgets` solves cross-platform widget development by abstracting native complexity behind a high-performance JSON layout protocol and declarative DSL: - **iOS 16.1+**: Maps `UI.*` nodes to SwiftUI primitives in WidgetKit (`DynamicNodeView.swift`). Supports ActivityKit for Live Activities on Lock Screen and Dynamic Island (expanded, compactLeading, compactTrailing, minimal). Supports iOS 17+ interactive `AppIntents`. - **Android API 24 -> Android 16 (API 36)**: Maps `UI.*` nodes to a high-DPI 2D `Canvas` renderer (`DynamicWidgetCanvasRenderer.kt`) for Home Screen `AppWidgetProvider`, and uses `Notification.ProgressStyle` / Ongoing Notifications for Live Activities with interactive action buttons and segmented progress bars. - **Shared Storage**: Uses iOS `UserDefaults(suiteName: appGroup)` and Android `SharedPreferences` to synchronize state with zero latency. --- ## 2. API Signature & Type Definitions ```typescript export interface StartActivityOptions { activityName: string; appGroup?: string; layout: WidgetNode; dynamicIsland?: { compactLeading?: WidgetNode; compactTrailing?: WidgetNode; minimal?: WidgetNode; expanded?: { leading?: WidgetNode; trailing?: WidgetNode; center?: WidgetNode; bottom?: WidgetNode; }; }; attributes?: Record; androidConfig?: { channelId?: string; channelName?: string; notificationId?: number; smallIcon?: string; ongoing?: boolean; color?: string; }; } export interface WidgetLayoutConfig { layout?: WidgetNode; small?: WidgetNode; medium?: WidgetNode; large?: WidgetNode; pages?: Record; initialPage?: string; accessoryRectangular?: WidgetNode; accessoryCircular?: WidgetNode; accessoryInline?: WidgetNode; } export interface WidgetRemoteConfig { url: string; method?: 'GET' | 'POST'; headers?: Record; intervalMinutes?: number; body?: Record; } ``` ### Static API Methods - `LiveActivity.start(options: StartActivityOptions): Promise`: Starts an activity, returns `activityId`. - `LiveActivity.update(options: { activityId?: string; layout?: WidgetNode; dynamicIsland?: ... }): Promise` - `LiveActivity.end(options: { activityId?: string; dismissalPolicy?: 'immediate'|'default' }): Promise` - `LiveActivity.endAll(): Promise` - `LiveActivity.getAllPushTokens(activityId?: string): Promise` - `LiveActivity.registerAction(actionId: string, handler: ActionHandler): () => void` - `LiveActivity.registerActionHandler(handler: (actionId: string, payload?: any) => void): () => void` - `Widget.setLayout(widgetKey: string, config: WidgetLayoutConfig, appGroup?: string): Promise` (alias: `Widget.update`) - `Widget.reload(widgetKey?: string): Promise` - `Widget.reloadAll(): Promise` - `Widget.setRemoteConfig(widgetKey: string, config: WidgetRemoteConfig, appGroup?: string): Promise` (supports shorthand `Widget.setRemoteConfig(config, appGroup?)`) - `Widget.onWidgetAction(handler: (actionId: string, payload?: any) => void): () => void` - `Widget.requestPin(): Promise`: Android only. ### React Hooks (Fast Refresh Resilient) - `useWidgetAction(actionIdOrCallback: string | ((actionId: string, payload?: any) => void), handler?: ActionHandler): void` - `useLiveActivity(initialActivityId?: string): UseLiveActivityResult` - `useWidgetState(key: string, initialValue: T, appGroup?: string): [T, (val: T | ((prev: T) => T)) => Promise, () => Promise]` ### In-App Widget Preview Component - ` ...} />` (alias: ``) ### Dual UI Authoring Syntax - **JSX Components**: ``, ``, ``, ``, ``, `