React Native Home Widget

A React Native library for creating home screen widgets on both iOS and Android.

Features

• ✅ Cross-platform support (iOS 14+ and Android API 21+)
• ✅ TypeScript support
• ✅ Easy-to-use API
• ✅ Customizable widget appearance
• ✅ Widget click handling
• ✅ Real-time widget updates
• ✅ Data persistence between app and widgets
• ✅ Multiple widget support

Installation

npm install react-native-home-widget
# or
yarn add react-native-home-widget

iOS Setup

1. Add the widget extension to your iOS project:

   • Open your iOS project in Xcode
   • Add a new Widget Extension target
   • Copy the files from ios/HomeWidgetExtension/ to your widget extension

2. Configure App Groups for data sharing:

   • In Xcode, select your main app target
   • Go to "Signing & Capabilities" tab
   • Add "App Groups" capability
   • Create a new group: group.com.reactnativehomewidget
   • Repeat the same for your widget extension target

3. Update your Podfile:

   pod 'ReactNativeHomeWidget', :path => '../node_modules/react-native-home-widget'

4. Run pod install in the ios directory

Android Setup

1. Add the following to your android/settings.gradle:

   include ':react-native-home-widget'
   project(':react-native-home-widget').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-home-widget/android')

2. Add the following to your android/app/build.gradle:

   dependencies {
       implementation project(':react-native-home-widget')
   }

3. Register the package in your MainApplication.java:

   import com.reactnativehomewidget.ReactNativeHomeWidgetPackage;
      
   @Override
   protected List<ReactPackage> getPackages() {
       return Arrays.<ReactPackage>asList(
           new MainReactPackage(),
           new ReactNativeHomeWidgetPackage() // Add this line
       );
   }

Usage

Basic Example

import React, { useEffect } from 'react';
import { View, Text, Button } from 'react-native';
import HomeWidget from 'react-native-home-widget';

const App = () => {
  useEffect(() => {
    // Check if widgets are supported
    HomeWidget.isSupported().then(supported => {
      if (supported) {
        console.log('Home widgets are supported!');
      }
    });

    // Set up widget click handler
    HomeWidget.setWidgetClickHandler((widgetId, data) => {
      console.log('Widget clicked:', widgetId, data);
    });
  }, []);

  const registerWidget = async () => {
    try {
      await HomeWidget.registerWidget({
        widgetId: 'my-widget',
        widgetName: 'My Widget',
        description: 'A sample widget',
        category: 'general'
      });
      console.log('Widget registered successfully');
    } catch (error) {
      console.error('Failed to register widget:', error);
    }
  };

  const updateWidget = async () => {
    try {
      await HomeWidget.updateWidget('my-widget', {
        id: 'my-widget',
        title: 'Hello World!',
        content: 'This is my first widget',
        backgroundColor: '#4CAF50',
        textColor: '#FFFFFF',
        actionUrl: 'myapp://widget-clicked'
      });
      console.log('Widget updated successfully');
    } catch (error) {
      console.error('Failed to update widget:', error);
    }
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>React Native Home Widget Example</Text>
      <Button title="Register Widget" onPress={registerWidget} />
      <Button title="Update Widget" onPress={updateWidget} />
    </View>
  );
};

export default App;

Troubleshooting

iOS Issues

1. Widget not updating: Make sure App Groups are properly configured for both the main app and widget extension
2. Data not persisting: Verify that the App Group identifier matches in both targets
3. Widget not appearing: Ensure the widget extension is properly added to your Xcode project

Android Issues

1. Widget not responding to clicks: Check that the widget provider is properly registered in AndroidManifest.xml
2. Widget not updating: Verify that the widget provider has the correct permissions
3. Build errors: Make sure all required dependencies are properly linked

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT