react-native-android-widget

When building widgets with react-native-android-widget, you must follow specific constraints because widgets are rendered by the Android system, not the React Native runtime.

Core Constraints

• No Hooks: Widget components must not use any React hooks (e.g., useState, useEffect).
• Primitive-only UI: Widgets must be functions that return only the library's provided primitives. You cannot use standard React Native components like View, Text, or Image inside a widget.
• Synchronous Execution: You can use standard JSX, conditions, and loops (for, map), but the component function cannot be async.

Supported Primitives

The library provides the following primitives to build your UI:

• FlexWidget
• OverlapWidget
• ListWidget
• TextWidget
• ImageWidget
• IconWidget
• SvgWidget

This library does not render React Native views directly to the Android widget. Instead, it follows a two-step process:

1. It renders the React Native views into an image.
2. It displays that image within the Android widget.

Because of this approach, the quality and fit of the widget depend heavily on knowing the exact size of the widget to ensure the generated image matches the widget dimensions correctly.

The library allows you to provide separate React element trees for light and dark system themes. When rendering or updating a widget, you pass an object containing light and/or dark keys. The Android system automatically selects the appropriate tree based on the current system theme. If the dark key is omitted, the light variant serves as the fallback for both modes.

// Example of the object structure passed to renderWidget
{
  light: <MyWidget theme="light" />,
  dark: <MyWidget theme="dark" />
}

If your Expo project uses Expo Router, you must redirect the entry point to a custom file to allow widget registration.

1. Update the main field in package.json from expo-router/entry to index.ts.
2. Create an index.ts file that imports expo-router/entry and then calls registerWidgetTaskHandler with your handler function.

// package.json
{
  "name": "my-expo-app",
  "main": "index.ts"
}

// index.ts
import 'expo-router/entry';
import { widgetTaskHandler } from './widget-task-handler';

registerWidgetTaskHandler(widgetTaskHandler);

You can schedule periodic updates using the updatePeriodMillis option (or android:updatePeriodMillis in native Android configurations).

When a scheduled update occurs, the widgetTaskHandler function is triggered with widgetAction set to 'WIDGET_UPDATE'. You should handle this case by calling props.renderWidget() with your widget component.

Important Limitation: Android restricts these scheduled updates; they will not be delivered more than once every 30 minutes.

export async function widgetTaskHandler(props: WidgetTaskHandlerProps) {
  switch (props.widgetAction) {
    case 'WIDGET_UPDATE':
      props.renderWidget(<Widget />);
      break;
    // ... other cases
  }
}

When a user clicks a primitive, the registerWidgetTaskHandler is triggered with a widgetAction of 'WIDGET_CLICK'. You can identify which specific action was triggered by checking props.clickAction against the string you provided in the widget definition. Any additional data passed via clickActionData is available in props.clickActionData.

export async function widgetTaskHandler(props: WidgetTaskHandlerProps) {
  switch (props.widgetAction) {
    // ... other cases

    case 'WIDGET_CLICK':
      if (props.clickAction === 'MY_ACTION') {
        // Do stuff when primitive with `clickAction="MY_ACTION"` is clicked
        // props.clickActionData === { id: 0 }
      }
      break;

    default:
      break;
  }
}

You can deploy the documentation website using either SSH or GitHub Pages.

Using SSH: Set the USE_SSH environment variable to true.

Using GitHub Pages: Provide your GitHub username via the GIT_USER environment variable. This will build the site and push it to the gh-pages branch.

# Deploy using SSH
$ USE_SSH=true yarn deploy

# Deploy to GitHub Pages
$ GIT_USER=<Your GitHub username> yarn deploy

In Expo, custom fonts are managed via the react-native-android-widget config plugin.

1. Place your font files in your assets directory (e.g., assets/fonts/Inter.ttf).
2. Update your app.config.ts (or app.json) to include the font paths in the react-native-android-widget plugin configuration.

export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: 'My Expo App Name',
  plugins: [
    ['react-native-android-widget', {
      fonts: ['./assets/fonts/Inter.ttf'],
      widgets: [...],
    }]
  ],
});