React Native Android Widget

https://saleksovski.github.io/react-native-android-widget/docs/
Admin
React Native Android Widget is an open-source library for building Android widgets using React...
Tokens:31,782
Snippets:267
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install react-native-android-widget with npm or yarn

Source: https://saleksovski.github.io/react-native-android-widget/docs

Install the react-native-android-widget library using either npm or yarn. Choose the command that matches your package manager.

```bash
npm install --save react-native-android-widget
```

```bash
yarn add react-native-android-widget
```

--------------------------------

### requestPinWidget usage example

Source: https://saleksovski.github.io/react-native-android-widget/docs/api/request-pin-widget

Calls `requestPinWidget` with a widget name and handles the boolean result. The promise resolves to `false` on unsupported platforms or launchers, and rejects if the widget name does not match a registered widget provider.

```javascript
import { requestPinWidget } from 'react-native-android-widget';  
  
const requested = await requestPinWidget({ widgetName: 'Fitness' });  
  
if (!requested) {  
  // Show manual instructions for launchers that do not support pin requests.  
}  

```

--------------------------------

### FlexWidget Usage Example

Source: https://saleksovski.github.io/react-native-android-widget/docs/primitives/flex-widget

Create a widget layout using the FlexWidget container. Nest child widgets inside and use the style prop with flexbox properties like alignItems and justifyContent, as shown in the example.

```jsx
import { FlexWidget } from 'react-native-android-widget';  
  
export function MyWidget() {  
  return (  
    <FlexWidget  
      style={{  
        alignItems: 'center',  
        justifyContent: 'center',  
      }}  
    >  
      ...  
    </FlexWidget>  
  );  
}  

```

--------------------------------

### HelloWidgetPreviewScreen.tsx - Using WidgetPreview

Source: https://saleksovski.github.io/react-native-android-widget/docs/api/widget-preview

Example of a screen component that uses WidgetPreview to render a HelloWidget with a width of 320 and height of 200. The component is centered on the screen using StyleSheet.

```tsx
import * as React from 'react';  
import { StyleSheet, View } from 'react-native';  
import { WidgetPreview } from 'react-native-android-widget';  
  
import { HelloWidget } from './HelloWidget';  
  
export function HelloWidgetPreviewScreen() {  
  return (  
    <View style={styles.container}>  
      <WidgetPreview  
        renderWidget={() => <HelloWidget />}  
        width={320}  
        height={200}  
      />  
    </View>  
  );  
}  
  
const styles = StyleSheet.create({  
  container: {  
    flex: 1,  
    alignItems: 'center',  
    justifyContent: 'center',  
  },  
});  

```

--------------------------------

### WidgetPreview

Source: https://saleksovski.github.io/react-native-android-widget/docs/api/widget-preview

Documentation for the WidgetPreview component exported by react-native-android-widget, including its props and a usage example.

```APIDOC
## WidgetPreview

### Description
A React Native component that renders a preview of a widget inside any screen of the application. It takes a render function that returns the widget's React element, along with the widget's dimensions.

### Props
- **renderWidget** (() => React.ReactElement) - Required - A function that returns the widget's React element to be previewed.
- **width** (number) - Required - The width of the widget preview in pixels.
- **height** (number) - Required - The height of the widget preview in pixels.

### Usage Example
```tsx
import * as React from 'react';
import { StyleSheet, View } from 'react-native';
import { WidgetPreview } from 'react-native-android-widget';

import { HelloWidget } from './HelloWidget';

export function HelloWidgetPreviewScreen() {
  return (
    <View style={styles.container}>
      <WidgetPreview
        renderWidget={() => <HelloWidget />}
        width={320}
        height={200}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});
```
```

--------------------------------

### OverlapWidget usage example

Source: https://saleksovski.github.io/react-native-android-widget/docs/primitives/overlap-widget

Use OverlapWidget to stack child widgets, positioning them with margin styles. The example imports OverlapWidget and FlexWidget from 'react-native-android-widget' and renders two FlexWidget children with different margins.

```jsx
import { OverlapWidget, FlexWidget } from 'react-native-android-widget';  
  
export function MyWidget() {  
  return (  
    <OverlapWidget>  
      <FlexWidget style={{ marginTop: 10, marginLeft: 10 }}>...</FlexWidget>  
      <FlexWidget style={{ marginTop: 20, marginLeft: 10 }}>...</FlexWidget>  
    </OverlapWidget>  
  );  
}  

```

--------------------------------

### Create widgetprovider_hello.xml

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/register-widget

Defines the AppWidget provider configuration for the widget. Set android:updatePeriodMillis to control update frequency (the task handler receives widgetAction = 'WIDGET_UPDATE'), android:previewImage to the preview image added previously, android:description if a description was added in the previous step, and android:widgetCategory to control where the widget may be placed.

```xml
<?xml version="1.0" encoding="utf-8"?>  
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"  
    android:minWidth="320dp"  
    android:minHeight="120dp"  
  
    android:targetCellWidth="5"  
    android:targetCellHeight="2"  
  
    android:updatePeriodMillis="0"  
  
    android:initialLayout="@layout/rn_widget"  
  
    android:previewImage="@drawable/hello_preview"  
    android:description="@string/widget_hello_description"  
  
    android:resizeMode="none"  
  
    android:widgetCategory="home_screen">  
</appwidget-provider>  

```

--------------------------------

### Create Hello.kt widget provider class

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/register-widget

Create a new package 'widget' in the native Android app and add this Kotlin class. The class name 'Hello' will be used to reference the widget.

```kotlin
package com.yourapppackage.widget  
  
import com.reactnativeandroidwidget.RNWidgetProvider  
  
class Hello : RNWidgetProvider() {  
}  

```

--------------------------------

### CounterScreen.tsx - requestWidgetUpdate example

Source: https://saleksovski.github.io/react-native-android-widget/docs/api/request-widget-update

Example of using requestWidgetUpdate inside a React useEffect to update a CounterWidget when the count state changes. The widgetNotFound callback is called if no widget is present on the home screen. The renderWidget can return a single element or an object with light and dark themes.

```tsx
import * as React from 'react';  
import { Button, StyleSheet, View, Text } from 'react-native';  
import { requestWidgetUpdate } from 'react-native-android-widget';  
  
import { CounterWidget } from './CounterWidget';  
  
export function CounterScreen() {  
  const [count, setCount] = React.useState(0);  
  
  React.useEffect(() => {  
    requestWidgetUpdate({  
      widgetName: 'Counter',  
      renderWidget: () => <CounterWidget count={count} />,  
      // or  
      // renderWidget: () => ({  
      //   light: <CounterWidget count={count} theme="light" />,  
      //   dark: <CounterWidget count={count} theme="dark" />,  
      // }),  
      widgetNotFound: () => {  
        // Called if no widget is present on the home screen  
      }  
    });  
  }, [count]);  
  
  return (  
    <View style={styles.container}>  
      <Text>{count}</Text>  
      <Button title="Increment" onPress={() => setCount(count + 1)} />  
      <Button title="Decrement" onPress={() => setCount(count - 1)} />  
    </View>  
  );  
}  
  
const styles = StyleSheet.create({  
  container: {  
    flex: 1,  
    alignItems: 'center',  
    justifyContent: 'center',  
  },  
});  

```

--------------------------------

### Create Hello.java widget provider class

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/register-widget

Create a new package 'widget' in the native Android app and add this Java class. The class name 'Hello' will be used to reference the widget.

```java
package com.yourapppackage.widget;  
  
import com.reactnativeandroidwidget.RNWidgetProvider;  
  
public class Hello extends RNWidgetProvider {  
}  

```

--------------------------------

### Add widget description string in strings.xml

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/register-widget

Optional: add a description string to strings.xml to show under the widget name in the launcher's widget picker.

```xml
<?xml version="1.0" encoding="utf-8"?>  
<resources>  
    <string name="app_name">My App Name</string>  
    <string name="widget_hello_description" translatable="false">This is my first widget</string>  
</resources>  

```

--------------------------------

### Usage: TextWidget with FlexWidget

Source: https://saleksovski.github.io/react-native-android-widget/docs/primitives/text-widget

Basic example of using TextWidget inside a FlexWidget to display text with custom style properties like fontSize, fontFamily, and color.

```jsx
import { FlexWidget, TextWidget } from 'react-native-android-widget';  
  
export function MyWidget() {  
  return (  
    <FlexWidget>  
      <TextWidget  
        text="Hello"  
        style={{  
          fontSize: 32,  
          fontFamily: 'Inter',  
          color: '#000000',  
        }}  
      />  
    </FlexWidget>  
  );  
}  

```

--------------------------------

### Widget preview image path

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/register-widget-expo

Place the widget preview image at this path inside the assets directory. The image is shown in the widget picker when the launcher displays the widget select popup.

```text
assets/widget-preview/hello.png
```

--------------------------------

### requestPinWidget

Source: https://saleksovski.github.io/react-native-android-widget/docs/api/request-pin-widget

Opens the Android launcher's native prompt for adding a widget to the home screen. Returns a promise that resolves to a boolean indicating whether the launcher accepted the request, and rejects if the widget name is invalid.

```APIDOC
## requestPinWidget

### Description
Opens the Android launcher's native prompt for adding one of your application's widgets to the home screen. Android supports this flow from API 26, but launcher support varies.

### Method
async function

### Signature
```typescript
requestPinWidget(options: { widgetName: string }): Promise<boolean>
```

### Parameters
#### Options
- **widgetName** (string) - Required - The name of the widget provider registered by the application.

### Request Example
```javascript
import { requestPinWidget } from 'react-native-android-widget';

const requested = await requestPinWidget({ widgetName: 'Fitness' });

if (!requested) {
  // Show manual instructions for launchers that do not support pin requests.
}
```

### Response
#### Success Response
- **Promise<boolean>** - Resolves to `true` if the launcher accepted the request and displayed its flow; `false` on unsupported platforms and launchers. The user may still cancel the confirmation dialog.

#### Error Handling
- The promise rejects if `widgetName` does not match a widget provider registered by the application.

```

--------------------------------

### index.ts - register widget configuration screen

Source: https://saleksovski.github.io/react-native-android-widget/docs/api/register-widget-configuration-screen

In the main index file, register the widget configuration screen along with the widget task handler. This is required for the configuration screen to open when adding or reconfiguring a widget.

```ts
import { AppRegistry } from 'react-native';  
import {  
  registerWidgetConfigurationScreen,  
  registerWidgetTaskHandler,  
} from 'react-native-android-widget';  
import { name as appName } from './app.json';  
import App from './App';  
import { widgetTaskHandler } from './widget-task-handler';  
import { WidgetConfigurationScreen } from './WidgetConfigurationScreen';  
  
AppRegistry.registerComponent(appName, () => App);  
registerWidgetTaskHandler(widgetTaskHandler);  
registerWidgetConfigurationScreen(WidgetConfigurationScreen);  

```

--------------------------------

### Expo config plugin with custom fonts

Source: https://saleksovski.github.io/react-native-android-widget/docs/primitives/icon-widget

Expo config plugin setup to include custom icon fonts. The fonts array must list all custom font files (e.g., './assets/fonts/material.ttf') that are placed in the assets directory. The widgets array is left as a placeholder and should be filled with your widget definitions.

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

```

--------------------------------

### Widget Interface

Source: https://saleksovski.github.io/react-native-android-widget/docs/public-api/interfaces/Widget

Documentation for the Widget interface, including all its properties and their descriptions.

```APIDOC
## Widget Interface

### Description
The `Widget` interface defines the configuration for an Android home screen widget in React Native Android Widget. It specifies properties such as name, dimensions, label, description, and various optional settings for widget behavior and appearance.

### Properties

#### name
- **Type**: `string`
- **Required**: Yes
- **Description**: Name of the widget which will be used to reference it in code.

#### minWidth
- **Type**: `${number}dp`
- **Required**: Yes
- **Description**: Minimum width of the widget in dp.

#### minHeight
- **Type**: `${number}dp`
- **Required**: Yes
- **Description**: Minimum height of the widget in dp.

#### label
- **Type**: `string`
- **Optional**: Yes
- **Description**: Label that will be shown in widget picker.

#### description
- **Type**: `string`
- **Optional**: Yes
- **Description**: Description that will be shown in widget picker.

#### targetCellWidth
- **Type**: `number`
- **Optional**: Yes
- **Description**: Target cell width for the widget.

#### targetCellHeight
- **Type**: `number`
- **Optional**: Yes
- **Description**: Target cell height for the widget.

#### maxResizeWidth
- **Type**: `${number}dp`
- **Optional**: Yes
- **Description**: Maximum resize width of the widget in dp.

#### maxResizeHeight
- **Type**: `${number}dp`
- **Optional**: Yes
- **Description**: Maximum resize height of the widget in dp.

#### previewImage
- **Type**: `./${string}` | `../${string}`
- **Optional**: Yes
- **Description**: Path to a preview image for the widget.

#### resizeMode
- **Type**: `"none"` | `"horizontal"` | `"vertical"` | `"horizontal|vertical"`
- **Optional**: Yes
- **Description**: Specifies the resize mode of the widget.

#### widgetFeatures
- **Type**: `"reconfigurable"` | `"reconfigurable|configuration_optional"`
- **Optional**: Yes
- **Description**: Whether the widget can be configured. 'configurable' means that the widget is configurable, and a configuration activity will be open when the widget is added on home screen. 'reconfigurable|configuration_optional' will make the widget configurable, but will not open the configuration activity when added on home screen, and the configuration can be changed by holding the widget and selecting configure. The widget will not be configurable if `widgetFeatures` is not provided.

#### widgetCategory
- **Type**: `"home_screen"` | `"keyguard"` | `"home_screen|keyguard"` | `"not_keyguard"`
- **Optional**: Yes
- **Default**: `"home_screen"`
- **Description**: Which surfaces the widget may be placed on. Android shows third-party widgets on the lock screen from Android 16 QPR2, and on some tablets from Android 15 QPR1. Widgets are eligible by default, but a host that filters on the declared category only offers widgets that name it, so `'home_screen|keyguard'` opts in explicitly. `'not_keyguard'` opts a widget out of the lock screen.

#### updatePeriodMillis
- **Type**: `number`
- **Optional**: Yes
- **Default**: `0`
- **Description**: How often the widget should be updated, in milliseconds. Default is 0 (no automatic updates). Minimum is 1.800.000 (30 minutes == 30 * 60 * 1000).

#### packageName
- **Type**: `string`
- **Optional**: Yes
- **Default**: `"<app-package-name>.widget"`
- **Description**: Custom Java package name for the widget's AppWidgetProvider. It must start with the actual apps package name. Can be used if introducing react-native-android-widget in existing app that already has widgets in a different package that the default one. Must not end with ".".
```

--------------------------------

### Create WidgetConfigurationActivity in Java

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/make-widget-configurable

Java class extending RNWidgetConfigurationActivity. Place in android/app/src/main/java/com/yourapppackage/WidgetConfigurationActivity.java.

```java
package com.yourapppackage;  
  
import com.reactnativeandroidwidget.RNWidgetConfigurationActivity;  
  
public class WidgetConfigurationActivity extends RNWidgetConfigurationActivity {  
}  

```

--------------------------------

### ListWidget usage with FlexWidget and TextWidget

Source: https://saleksovski.github.io/react-native-android-widget/docs/primitives/list-widget

Creates a scrollable ListWidget with 15 FlexWidget items, each containing a TextWidget. Each item uses clickAction OPEN_URI with a dynamic URI. Ensure each list item height is equal or less than the ListWidget height.

```jsx
import {  
  ListWidget,  
  FlexWidget,  
  TextWidget,  
} from 'react-native-android-widget';  
  
export function MyWidget() {  
  return (  
    <ListWidget  
      style={{  
        height: 'match_parent',  
        width: 'match_parent',  
        backgroundColor: '#1F3529',  
      }}  
    >  
      {Array.from({ length: 15 }).map((_, i) => (  
        <FlexWidget  
          key={i}  
          style={{  
            width: 'match_parent',  
            alignItems: 'center',  
            flexDirection: 'row',  
            justifyContent: 'center',  
            padding: 8,  
          }}  
          clickAction="OPEN_URI"  
          clickActionData={{  
            uri: `androidwidgetexample://list/list-demo/${i + 1}`,  
          }}  
        >  
          <TextWidget text={`React Native Android Widget Release 0.${i + 1}`} />  
        </FlexWidget>  
      ))}  
    </ListWidget>  
  );  
}  

```

--------------------------------

### Create WidgetConfigurationActivity in Kotlin

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/make-widget-configurable

Kotlin class extending RNWidgetConfigurationActivity. Place in android/app/src/main/java/com/yourapppackage/WidgetConfigurationActivity.kt.

```kotlin
package com.yourapppackage  
  
import com.reactnativeandroidwidget.RNWidgetConfigurationActivity  
  
class WidgetConfigurationActivity : RNWidgetConfigurationActivity() {  
}  

```

--------------------------------

### registerWidgetConfigurationScreen(WidgetConfigurationScreen)

Source: https://saleksovski.github.io/react-native-android-widget/docs/api/register-widget-configuration-screen

Registers a widget configuration screen component. When a configurable widget is added or reconfigured on the home screen, this screen is opened. The component receives props including widgetInfo, setResult, and renderWidget.

```APIDOC
## registerWidgetConfigurationScreen(WidgetConfigurationScreen)

### Description
Registers a widget configuration screen component. When a configurable widget is added or reconfigured on the home screen, this screen is opened. The component receives props including widgetInfo, setResult, and renderWidget.

### Method
registerWidgetConfigurationScreen

### Parameters
- **WidgetConfigurationScreen** (Component) - Required - The React component that renders the configuration UI. It receives WidgetConfigurationScreenProps.

### Usage Example
```tsx
import { registerWidgetConfigurationScreen } from 'react-native-android-widget';
import { WidgetConfigurationScreen } from './WidgetConfigurationScreen';

registerWidgetConfigurationScreen(WidgetConfigurationScreen);
```

### Notes
- The configuration screen can be canceled by calling `setResult('cancel')`. If the widget was just added, it will be removed from the home screen; otherwise, the configuration is canceled and the widget remains unchanged.
- To apply configuration changes, call `renderWidget` to update the widget and then `setResult('ok')` to close the screen.
- Multiple configurable widgets share the same configuration screen; use the `widgetInfo` prop to differentiate.

### WidgetConfigurationScreenProps
- **widgetInfo** (object) - Required - Information about the widget being configured.
- **setResult** (function) - Required - Call with 'ok' or 'cancel' to finish configuration.
- **renderWidget** (function) - Required - Call to update the widget with new configuration.
```

--------------------------------

### getWidgetInfo

Source: https://saleksovski.github.io/react-native-android-widget/docs/public-api

Returns a list of widgets with the given name that are added to the home screen.

```APIDOC
## getWidgetInfo(widgetName)

### Description
Returns a list of `widgetName` widgets added on the home screen.

### Method
Function

### Signature
`getWidgetInfo(widgetName: string): Promise<WidgetInfo[]>`

### Parameters
- **widgetName** (string) - Required - The name of the widget to query.

### Returns
`Promise<WidgetInfo[]>` - A promise that resolves to an array of `WidgetInfo` objects representing the widgets added on the home screen.
```

--------------------------------

### ImageWidgetProps

Source: https://saleksovski.github.io/react-native-android-widget/docs/public-api/interfaces/ImageWidgetProps

Documentation for the ImageWidgetProps interface, including all properties and their types, required status, and descriptions.

```APIDOC
## ImageWidgetProps

### Description
Interface for configuring an image widget in React Native Android Widget. It extends ClickActionProps and defines properties for the image source, dimensions, styling, and click behavior.

### Properties

#### imageWidth
- **Type**: `number`
- **Required**: Yes
- **Description**: Width of the image.

#### imageHeight
- **Type**: `number`
- **Required**: Yes
- **Description**: Height of the image.

#### image
- **Type**: `ImageWidgetSource`
- **Required**: Yes
- **Description**: Image loaded using `require('./path/to/image')`, or a path to image starting with "http:", "https:", or "data:/image".

#### style
- **Type**: `CommonStyleProps`
- **Required**: No
- **Description**: Style properties for the image.

#### radius
- **Type**: `number`
- **Required**: No
- **Description**: Image radius.

#### resizeMode
- **Type**: `"center" | "stretch" | "cover" | "contain"`
- **Required**: No
- **Description**: How the image should be resized when its aspect ratio differs from the view. Defaults to Android's ImageView behavior, which is equivalent to `contain`.

#### clickAction
- **Type**: `string`
- **Required**: No
- **Description**: A string that will define an action that will be emitted when clicking the widget. Special values: `"OPEN_APP"` (opens the application when clicked, does not require `clickActionData`), `"OPEN_URI"` (requires `clickActionData` containing `{ uri: 'some-uri' }`, can be a web URI or app deep link). Inherited from `ClickActionProps`.

#### clickActionData
- **Type**: `Record<string, unknown>`
- **Required**: No
- **Description**: Additional data passed when the widget is clicked. If `clickAction` is `OPEN_URI`, it must contain `{ uri: 'some-uri' }`. Inherited from `ClickActionProps`.

#### accessibilityLabel
- **Type**: `string`
- **Required**: No
- **Description**: Accessibility label for screen readers. Can be set on the root component or any clickable component. Inherited from `ClickActionProps`.
```

--------------------------------

### RequestPinWidgetOptions

Source: https://saleksovski.github.io/react-native-android-widget/docs/public-api/interfaces/RequestPinWidgetOptions

Interface that defines the options for requesting to pin a widget to the home screen. It contains the widgetName property, which is the name of the widget provider to add.

```APIDOC
## Interface: RequestPinWidgetOptions

### Description
Defines the options for requesting to pin a widget to the home screen.

### Properties

#### widgetName
- **Type**: `string`
- **Required**: Yes
- **Description**: The name of the widget provider to add to the home screen.
```

--------------------------------

### HelloWidget.tsx - Basic widget with 'use no memo'

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/widget-design

Defines a simple widget that displays 'Hello' using FlexWidget and TextWidget. Must be a function returning primitives only, no hooks. Add 'use no memo' at the top if React Compiler is enabled to prevent automatic memoization.

```tsx
'use no memo';  
import React from 'react';  
import { FlexWidget, TextWidget } from 'react-native-android-widget';  
  
export function HelloWidget() {  
  return (  
    <FlexWidget  
      style={{  
        height: 'match_parent',  
        width: 'match_parent',  
        justifyContent: 'center',  
        alignItems: 'center',  
        backgroundColor: '#ffffff',  
        borderRadius: 16,  
      }}  
      accessibilityLabel="Hello world widget"  
    >  
      <TextWidget  
        text="Hello"  
        style={{  
          fontSize: 32,  
          fontFamily: 'Inter',  
          color: '#000000',  
        }}  
      />  
    </FlexWidget>  
  );  
}  

```

--------------------------------

### index.ts - Expo registration

Source: https://saleksovski.github.io/react-native-android-widget/docs/api/register-widget-configuration-screen

Create an index.ts file for Expo, using node_modules/expo/AppEntry.js as a template. Import and register the widget task handler and configuration screen.

```ts
import { registerRootComponent } from 'expo';  
import {  
  registerWidgetConfigurationScreen,  
  registerWidgetTaskHandler,  
} from 'react-native-android-widget';  
  
import App from './App';  
import { widgetTaskHandler } from './widget-task-handler';  
import { WidgetConfigurationScreen } from './WidgetConfigurationScreen';  
  
// registerRootComponent calls AppRegistry.registerComponent('main', () => App);  
// It also ensures that whether you load the app in Expo Go or in a native build,  
// the environment is set up appropriately  
registerRootComponent(App);  
registerWidgetTaskHandler(widgetTaskHandler);  
registerWidgetConfigurationScreen(WidgetConfigurationScreen);  

```

--------------------------------

### Add WidgetConfigurationActivity to AndroidManifest.xml

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/make-widget-configurable

Add an activity with `android:name=".WidgetConfigurationActivity"` and an intent filter for `android.appwidget.action.APPWIDGET_CONFIGURE`. The `android:name` must be `.WidgetConfigurationActivity`.

```xml
<manifest ...>  
  ...  
  <application  
      android:name=".MainApplication"  
      ...>  
  
      <activity  
          android:name=".MainActivity"  
          ...>  
      </activity>  
  
      <activity android:name=".WidgetConfigurationActivity"  
          android:exported="true">  
          <intent-filter>  
              <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>  
          </intent-filter>  
      </activity>  
  </application>  
</manifest>  

```

--------------------------------

### Update widget provider XML with configure and widgetFeatures

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/make-widget-configurable

Add `android:configure` and `android:widgetFeatures` to the widget provider XML. `android:configure` references the configuration activity. `android:widgetFeatures` can be `reconfigurable` or `reconfigurable|configuration_optional`.

```xml
<?xml version="1.0" encoding="utf-8"?>  
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"  
    android:minWidth="320dp"  
    android:minHeight="120dp"  
  
    android:targetCellWidth="5"  
    android:targetCellHeight="2"  
  
    android:updatePeriodMillis="0"  
  
    android:initialLayout="@layout/rn_widget"  
  
    android:previewImage="@drawable/hello_preview"  
    android:description="@string/widget_hello_description"  
  
    android:resizeMode="none"  
  
  
    android:configure="com.yourapppackage.WidgetConfigurationActivity"  
    android:widgetFeatures="reconfigurable"  
  
  
    android:widgetCategory="home_screen">  
</appwidget-provider>  

```

--------------------------------

### WidgetConfigurationScreen.tsx - configuration component

Source: https://saleksovski.github.io/react-native-android-widget/docs/api/register-widget-configuration-screen

Create a widget configuration component that receives widgetInfo, setResult, and renderWidget props. Use this to define the UI for configuring the widget.

```tsx
import React from 'react';  
import type { WidgetConfigurationScreenProps } from 'react-native-android-widget';  
import { ConfigurableWidget } from './ConfigurableWidget';  
  
export function WidgetConfigurationScreen({  
  widgetInfo,  
  setResult,  
  renderWidget,  
}: WidgetConfigurationScreenProps) {  
  // Here we can define the UI for configuring the widget  
}  

```

--------------------------------

### WidgetConfigurationScreenProps

Source: https://saleksovski.github.io/react-native-android-widget/docs/public-api/interfaces/WidgetConfigurationScreenProps

Interface defining the properties passed to a widget configuration screen. It provides access to widget information, a render function, and a result setter.

```APIDOC
## Interface: WidgetConfigurationScreenProps

### Description
Properties passed to a widget configuration screen component. Includes widget information, a render function, and a result setter.

### Properties

#### widgetInfo
- **Type**: `WidgetInfo`
- **Description**: Information about the widget being configured.

#### renderWidget
- **Type**: (`widgetComponent`: `WidgetRepresentation`) => `void`
- **Description**: Function that can be called with the Widget JSX to render.
- **Parameters**:
  - `widgetComponent` (`WidgetRepresentation`) - The widget JSX representation to render.
- **Returns**: `void`

#### setResult
- **Type**: (`result`: `"ok"` | `"cancel"`) => `void`
- **Description**: This must be called after finishing with configuration. 'ok' means the widget is configured and can be added, 'cancel' means the configuration process is canceled and the widget will be removed if this is the first time configuring it.
- **Parameters**:
  - `result` (`"ok"` | `"cancel"`) - The configuration result.
- **Returns**: `void`
```

--------------------------------

### WidgetPreviewProps

Source: https://saleksovski.github.io/react-native-android-widget/docs/public-api/interfaces/WidgetPreviewProps

The WidgetPreviewProps interface defines the configuration for the WidgetPreview component. It includes required properties for rendering the widget and optional properties for interaction and styling.

```APIDOC
## Interface: WidgetPreviewProps

### Description
Defines the properties for the WidgetPreview component.

### Properties

#### renderWidget
- **Type**: `(props: { width: number; height: number }) => Element`
- **Required**: Yes
- **Description**: Callback function that will be called by `WidgetPreview` to generate the widget UI.

#### height
- **Type**: `number`
- **Required**: Yes
- **Description**: The height of the widget.

#### width
- **Type**: `number`
- **Required**: Yes
- **Description**: The width of the widget.

#### onClick
- **Type**: `(props: OnClick) => void`
- **Required**: No
- **Description**: Callback function that will be called when clicked on a clickable area of the widget.

#### showBorder
- **Type**: `boolean`
- **Required**: No
- **Description**: Whether to show a border around the widget. Useful for widgets that do not use the whole space.

#### highlightClickableAreas
- **Type**: `boolean`
- **Required**: No
- **Description**: Whether to add a highlight to the clickable areas.

```

--------------------------------

### ScreenInfo Interface

Source: https://saleksovski.github.io/react-native-android-widget/docs/public-api/interfaces/ScreenInfo

The ScreenInfo interface defines the properties that describe a device screen's dimensions and density.

```APIDOC
## Interface: ScreenInfo

### Description
Represents screen information including dimensions and density.

### Properties
- **screenHeightDp** (`number`) - Height of the screen in DP
- **screenWidthDp** (`number`) - Width of the screen in DP
- **density** (`number`) - Density of the screen
- **densityDpi** (`number`) - Density of the screen in Dpi

```

--------------------------------

### Create widget task handler function (widget-task-handler.tsx)

Source: https://saleksovski.github.io/react-native-android-widget/docs/tutorial/register-task-handler

Defines an async widgetTaskHandler that maps widget names to components and handles widget actions. The switch handles WIDGET_ADDED, WIDGET_UPDATE, WIDGET_RESIZED, WIDGET_DELETED, and WIDGET_CLICK, with only WIDGET_ADDED rendering the widget for now.

```tsx
import React from 'react';  
import type { WidgetTaskHandlerProps } from 'react-native-android-widget';  
import { HelloWidget } from './HelloWidget';  
  
const nameToWidget = {  
  // Hello will be the **name** with which we will reference our widget.  
  Hello: HelloWidget,  
};  
  
export async function widgetTaskHandler(props: WidgetTaskHandlerProps) {  
  const widgetInfo = props.widgetInfo;  
  const Widget =  
    nameToWidget[widgetInfo.widgetName as keyof typeof nameToWidget];  
  
  switch (props.widgetAction) {  
    case 'WIDGET_ADDED':  
      props.renderWidget(<Widget />);  
      break;  
  
    case 'WIDGET_UPDATE':  
      // Not needed for now  
      break;  
  
    case 'WIDGET_RESIZED':  
      // Not needed for now  
      break;  
  
    case 'WIDGET_DELETED':  
      // Not needed for now  
      break;  
  
    case 'WIDGET_CLICK':  
      // Not needed for now  
      break;  
  
    default:  
      break;  
  }  
}  

```

--------------------------------

### Async fetch in WIDGET_CLICK handler

Source: https://saleksovski.github.io/react-native-android-widget/docs/api/register-widget-task-handler

Shows how to perform asynchronous operations like fetching data from an API inside the widget task handler. In the WIDGET_CLICK case, it fetches data and renders the widget with the fetched title.

```typescript
// ...  
case 'WIDGET_CLICK':  
  if (props.clickAction === 'refresh') {  
    const data = await fetch('https://example.com/api').then((response) => response.json());  
    props.renderWidget(<Widget title={data.title} />);  
  }  
  break;  

```
Tokens:
Raw