Registry / web-framework / react-native-android-widget

react-native-android-widget

JSON →
library0.20.1jsnpmunverified

`react-native-android-widget` is an open-source library that empowers developers to build native Android home screen widgets directly using React Native components and paradigms. It bridges the gap between React's declarative UI approach and the Android widget framework, minimizing the need for native Java/Kotlin code for UI definition. The package is currently at stable version 0.20.1 and maintains a frequent release cadence, regularly adding support for the latest React Native versions (e.g., 0.83, 0.79) and enhancing functionality. Key differentiators include built-in accessibility (TalkBack) support, dark mode capabilities, and compatibility with the new React Native architecture. It provides tools for quick iteration through a `WidgetPreview` component and simplifies the complex process of registering and updating widgets.

npm install react-native-android-widget
INSTALL
IMPORT
SIG · REACT-NATIVE-ANDRO
R
react-native-android-widget
web-frameworkjavascriptv0.20.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

registerWidget
import { registerWidget } from 'react-native-android-widget';
const { registerWidget } = require('react-native-android-widget');
Used in the main entry file (e.g., `index.ts`) to make widgets discoverable by the Android system. Requires native configuration in `app.json` for Expo or `AndroidManifest.xml` for bare projects.
WidgetPreview
import { WidgetPreview } from 'react-native-android-widget';
import WidgetPreview from 'react-native-android-widget/WidgetPreview';
A utility component for previewing widgets within your React Native application during development, significantly speeding up the design process by avoiding constant redeploys to the home screen.
FlexWidget
import { FlexWidget, TextWidget } from 'react-native-android-widget';
import { View, Text } from 'react-native';
These are specialized components (`FlexWidget`, `TextWidget`, `ImageWidget`, etc.) that must be used to define the UI of your Android widget, as standard React Native `View` and `Text` components are not directly renderable in `RemoteViews` for Android widgets.
registerWidgetTaskHandler
import { registerWidgetTaskHandler } from 'react-native-android-widget';
import registerWidgetTaskHandler from 'react-native-android-widget/taskHandler';
Registers the JavaScript task handler that will be invoked by the native Android side to update widget data or respond to interactions (e.g., clicks, updates).

This quickstart demonstrates how to define a basic Android widget using `FlexWidget` and `TextWidget`, register it for the Android system, set up a JavaScript task handler for widget events, and preview the widget within a React Native app using `WidgetPreview`.

import { TextWidget, FlexWidget, registerWidget, WidgetPreview, registerWidgetTaskHandler, RNWidgetJsCommunication, } from 'react-native-android-widget'; import { useEffect, useState } from 'react'; import { AppRegistry, SafeAreaView, StyleSheet, Button } from 'react-native'; const HelloWorldWidget = () => { const [count, setCount] = useState(0); useEffect(() => { // This effect runs only in the React Native app, not the widget console.log('Widget component mounted in app preview'); }, []); return ( <FlexWidget style={{ height: 'match_parent', width: 'match_parent', backgroundColor: '#f0f0f0', borderRadius: 16, justifyContent: 'center', alignItems: 'center', padding: 16, }} > <TextWidget text={`Hello from Widget! Count: ${count}`} style={{ fontSize: 24, fontWeight: 'bold', color: '#333333', textAlign: 'center', }} /> <TextWidget text="Click to increment (in app)" style={{ fontSize: 14, color: '#666666', marginTop: 8, }} /> </FlexWidget> ); }; // A minimal task handler for the widget to receive events const widgetTaskHandler = async (taskData: any) => { const { widgetId, widgetName, action } = taskData; console.log(`Handling task for ${widgetName} (${widgetId}): ${action}`); if (action === 'WIDGET_ADDED' || action === 'WIDGET_UPDATE') { // You might fetch fresh data here or update widget content console.log('Widget added or updated. Scheduling next update.'); } if (action === 'WIDGET_CLICK') { // Example: Update the widget with new data or open the app RNWidgetJsCommunication.requestWidgetUpdate(widgetName); } }; // Register the widget for Android system discovery registerWidget('HelloWorldWidget', () => HelloWorldWidget); // Register the task handler for widget lifecycle and interaction events registerWidgetTaskHandler(widgetTaskHandler); // App component to render the WidgetPreview const App = () => { const [previewCount, setPreviewCount] = useState(0); return ( <SafeAreaView style={styles.container}> <WidgetPreview name="HelloWorldWidget" initialProps={{ count: previewCount }} style={styles.previewContainer} /> <Button title="Increment Preview Count" onPress={() => setPreviewCount(prev => prev + 1)} /> </SafeAreaView> ); }; const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', backgroundColor: '#ffffff', }, previewContainer: { width: 300, height: 150, backgroundColor: '#eee', marginBottom: 20, borderWidth: 1, borderColor: '#ccc', borderRadius: 8, overflow: 'hidden' } }); AppRegistry.registerComponent('YourAppName', () => App);
Debug
Known issues
breakingVersion 0.15.1 dropped support for React Native versions older than 0.76. Projects on older RN versions must remain on `react-native-android-widget` version 0.14.2 or earlier.
fix
Upgrade your React Native project to version 0.76 or higher. Alternatively, pin `react-native-android-widget` to version `0.14.2` if an RN upgrade is not feasible.
affects: >=0.15.1
gotchaUsing React Compiler (or experimental React features) can lead to 'Invalid hook call' errors in widget components due to the separate JavaScript environment where widget code runs.
fix
As of v0.17.3, an error message is added, but the general fix involves ensuring widget-related files (those passed to `registerWidget`) do not use React Compiler or other experimental React features that rely on a specific React context. You might need to adjust your Babel configuration to exclude these files from certain transformations.
affects: >=0.17.3
breakingSupport for the new React Native architecture was introduced in v0.16.0. While this is an 'added' feature, transitioning an existing project from the old architecture to the new one with this library may require specific configuration adjustments and testing.
fix
Consult the React Native documentation for migrating to the New Architecture and ensure your `android/build.gradle` and `android/gradle.properties` are configured correctly. Test widget functionality thoroughly after migration.
affects: >=0.16.0
gotchaAndroid widgets are based on `RemoteViews` and have layout restrictions; they do not support all React Native components or custom views directly. Only the specific components exported by `react-native-android-widget` (e.g., `FlexWidget`, `TextWidget`, `ImageWidget`) can be used for widget UI.
fix
Always use the provided `react-native-android-widget` components (`FlexWidget`, `TextWidget`, `ImageWidget`, etc.) to construct your widget UI. Do not attempt to use standard `react-native` components like `<View>` or `<Text>` directly within your widget definition.
affects: All versions
Errors
Common errors & fixes
Error: Invalid hook call. Hooks can only be called inside of the body of a function component.
This typically occurs when using experimental React features or the React Compiler with widget components, which execute in a different JavaScript context than the main React Native app.
fix
Ensure that the React components used to define your widgets (e.g., the component passed to `registerWidget`) do not use React Compiler or other experimental React features. You might need to configure your Babel setup to exclude widget files from specific transformations or revert to stable React versions for widget definitions.
NullPointerException in some cases in ImageWidget
An internal error within the `ImageWidget` component, potentially related to how bitmaps or image resources are handled, especially when dealing with lists or dynamic images.
fix
This issue was specifically fixed in version `0.16.1` and `0.17.1`. Ensure you are on the latest stable version of `react-native-android-widget` (`>=0.20.1`). If the problem persists, review image sources and caching mechanisms for potential edge cases.
Widget not appearing in Android launcher's widget picker.
The widget might not be correctly registered in the native `AndroidManifest.xml` or `app.json` (for Expo projects), or the widget provider class is incorrectly defined.
fix
For Expo projects, verify your `app.json` includes the `react-native-android-widget` plugin with the correct widget configurations (name, label, preview image, etc.). For bare React Native projects, ensure you have correctly added the `AppWidgetProvider` class and its receiver entry in `AndroidManifest.xml` as per the library's documentation.
Upgrade
Version history
0.20.1latest on npm
Audit
Dependencies
expooptionalPeer dependency for Expo projects, enabling widget integration within the Expo ecosystem. Required for projects using Expo workflows.
reactrequiredCore React library, fundamental for defining components used in widgets.
react-nativerequiredCore React Native framework, essential for building the application and the widget's underlying structure.
Agent activity
2 hits · last 30 days
node
2
Resources
react-native-android-widget — npm install react-native-android-widget · libregistry