Registry /
web-framework / react-native-android-widget
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
muslnode 18–226 runs
build_error
glibcnode 18–226 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);
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.
fixEnsure 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.
fixThis 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.
fixFor 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.
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.