### Install React Native Android Widget with npm

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

Use this command to install the library using npm.

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

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

### Install React Native Android Widget with yarn

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

Use this command to install the library using yarn.

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

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

### Combined Accessibility Example

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

This example demonstrates combining accessibilityLabels for the root widget, interactive icons, and list items, providing comprehensive screen reader support.

```typescript
export function EmailWidget() {
  return (
    <FlexWidget
      style={{ ... }}
      accessibilityLabel="Email widget"
    >
      <IconWidget
        icon="edit"
        font="material_outlined"
        style={{ ... }}
        clickAction="COMPOSE"
        accessibilityLabel="Compose new email"
      />
      <ListWidget
        style={{ ... }}
      >
        <FlexWidget
          style={{ ... }}
          accessibilityLabel={`Email 1 of 2, title: React Native Android Widget Release 0.1`}
        >
          <TextWidget style={{ ... }} text="React Native Android Widget Release 0.1" />
          <IconWidget
            icon="archive"
            font="material_outlined"
            clickAction="ARCHIVE"
            clickActionData={{ listItemId: 1 }}
            accessibilityLabel="Archive email"
          />
        </FlexWidget>
        <FlexWidget
          style={{ ... }}
          accessibilityLabel={`Email 2 of 2, title: React Native Android Widget Release 0.2`}
        >
          <TextWidget style={{ ... }} text="React Native Android Widget Release 0.2" />
          <IconWidget
            icon="archive"
            font="material_outlined"
            clickAction="ARCHIVE"
            clickActionData={{ listItemId: 2 }}
            accessibilityLabel="Archive email"
          />
        </FlexWidget>
      </ListWidget>
    </FlexWidget>
  );
}

```

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

### Widget Configuration Component Example

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

This component defines the UI for configuring a widget. It receives `widgetInfo`, `setResult`, and `renderWidget` as props.

```typescript
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
}
```

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

### ClickActionData for OPEN_URI

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

When using OPEN_URI, the clickActionData must include a URI. This example shows the expected format for the data.

```typescript
{
  uri: 'some-uri'
}
```

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

### Request Widget Update Example

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

Use this snippet to update a widget on the Android home screen. It takes a widget name and a render function. The render function can return a single widget or an object with light and dark themes. An optional callback handles cases where the widget is not found.

```typescript
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',
  },
});

```

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

### Define Widget Task Handler Function

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

Create a task handler function to manage different widget actions such as adding, updating, resizing, deleting, or handling clicks. This example demonstrates handling various widget events and rendering components based on the action.

```typescript
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 />);
      // or
      // props.renderWidget({
      //   light: <Widget theme="light" />,
      //   dark: <Widget theme="dark" />,
      // });
      break;

    case 'WIDGET_UPDATE':
      props.renderWidget(<Widget />);
      break;

    case 'WIDGET_RESIZED':
      props.renderWidget(<Widget />);
      break;

    case 'WIDGET_DELETED':
      // Handle widget deleted (remove widget data if you stored it somewhere)
      break;

    case 'WIDGET_CLICK':
      if (props.clickAction === 'play') {
        props.renderWidget(<Widget status="playing" />);
      } else {
        props.renderWidget(<Widget status="stopped" />);
      }
      break;

    default:
      break;
  }
}
```

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

### Register Widget Task Handler in index.ts

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

Register the widget task handler in your application's main entry point (`index.ts` or `index.js`). This ensures that the handler is active and can process widget events from the moment the app starts.

```typescript
import { AppRegistry } from 'react-native';
import { registerWidgetTaskHandler } from 'react-native-android-widget';
import { name as appName } from './app.json';
import App from './App';
import { widgetTaskHandler } from './widget-task-handler';

AppRegistry.registerComponent(appName, () => App);
registerWidgetTaskHandler(widgetTaskHandler);
```

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

### Basic FlexWidget Usage

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

Demonstrates how to import and use the FlexWidget with basic alignment and justification styles.

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

```

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

### Basic TextWidget Usage

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

Demonstrates how to use the TextWidget to display 'Hello' with custom font styles like size, family, and color. Ensure FlexWidget is used as a parent.

```javascript
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 Description String

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

Add an optional description for your widget in the strings.xml file. This text will appear under the widget's name in the launcher.

```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>
```

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

### Basic Hello Widget

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

A simple widget that displays 'Hello' using FlexWidget and TextWidget. Add 'use no memo' at the top if React Compiler is enabled to prevent automatic memoization.

```typescript
'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>
  );
}

```

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

### Widget Provider XML Configuration

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

Configure widget properties such as minimum dimensions, update period, initial layout, preview image, and description in this XML file.

```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>
```

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

### Widget Preview Image Path

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

Place a screenshot of your widget in the drawable resource directory to be used as a preview in the launcher's widget picker.

```plaintext
android/app/src/main/res/drawable/hello_preview.png
```

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

### Basic ListWidget Usage

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

Demonstrates how to use the ListWidget to display a scrollable list of items. Each item is a FlexWidget containing a TextWidget. The widget is configured to fill the parent container and has a dark green background. Clicking an item opens a specific URI.

```javascript
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>
  );
}

```

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

### OPEN_APP Click Action

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

Use 'OPEN_APP' for clickAction to open the application without needing additional data. This action is executed when the widget section is clicked.

```typescript
"OPEN_APP"
```

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

### Previewing a Widget with WidgetPreview

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

Use the WidgetPreview component to render a widget preview. Specify the widget to render using the 'renderWidget' prop and set the desired dimensions with 'width' and 'height'.

```typescript
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',
  },
});

```

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

### Using SvgWidget with Different SVG Sources

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

Demonstrates how to use SvgWidget to display SVGs from a local file, an SVG string, and a network URL. Ensure the necessary imports are included.

```javascript
import { FlexWidget, SvgWidget } from 'react-native-android-widget';  
  
const svgString = `  
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="100%" height="100%" viewBox="0 0 300 300">  
  ...  
</svg>  
`;  
  
export function MyWidget() {  
  return (  
    <FlexWidget>  
      <SvgWidget  
        svg={require('../assets/SVG_Logo.svg')}  
        style={{ height: 72, width: 72 }}  
      />  
  
      <SvgWidget  
        svg={svgString}  
        style={{ height: 72, width: 72 }}  
      />  
  
      <SvgWidget  
        svg="https://upload.wikimedia.org/wikipedia/commons/4/4f/SVG_Logo.svg"  
        style={{ height: 72, width: 72 }}  
      />  
    </FlexWidget>  
  );
}
```

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

### Widget Preview Image Path

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

Specify the path to your widget's preview image within the assets directory. This image is displayed in the widget selection popup.

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

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

### Basic OverlapWidget Usage

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

Demonstrates how to use OverlapWidget to stack multiple FlexWidgets. Child widgets are positioned using margin styles.

```javascript
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>  
  );
}
```

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

### Widget Provider XML Configuration

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

Configure the widget provider XML to enable reconfigurability and specify the configuration activity.

```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>
```

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

### Opening App with clickAction OPEN_APP

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

Use the special `clickAction` value `"OPEN_APP"` to open the application when a widget section is clicked. This action does not require `clickActionData`.

```javascript
<FlexWidget clickAction="OPEN_APP">
  ...
</FlexWidget>
```

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

### WidgetPreview

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

Renders a preview of a widget. This is a functional component that accepts widget preview properties.

```APIDOC
## WidgetPreview

### Description
Renders a preview of a widget. This component is used to display how a widget will look.

### Parameters
#### Destructured Parameters
- **(props)** (`WidgetPreviewProps`) - The properties required for rendering the widget preview.
```

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

### WidgetConfigurationScreenProps

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

Defines the properties for the widget configuration screen, including widget information, rendering capabilities, and result setting.

```APIDOC
## Interface: WidgetConfigurationScreenProps

### Properties

#### widgetInfo

- **widgetInfo** (WidgetInfo) - Required - Information about the widget being configured.

#### renderWidget

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

#### setResult

- **setResult** ((result: "ok" | "cancel") => void) - Required - 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 outcome of the configuration process.
  - **Returns**: void
```

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

### getWidgetInfo

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

Retrieves information about widgets of a specific name that are currently added to the home screen. It returns a promise that resolves to an array of WidgetInfo objects.

```APIDOC
## getWidgetInfo

### Description
Returns a list of widgets of a specified name that have been added to the home screen.

### Method
GET (conceptual)

### Parameters
#### Path Parameters
- **widgetName** (string) - Required - The name of the widget to retrieve information for.

### Returns
#### Success Response
- `Promise<WidgetInfo[]>` - A promise that resolves to an array of WidgetInfo objects.
```

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

### SizeStyleProps

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

Defines the optional properties for height and width, which can be a number or specific string values.

```APIDOC
## Interface: SizeStyleProps

### Properties

#### height

- `Optional` **height**: `number` | `"wrap_content"` | `"match_parent"`
  
  Specifies the height of the element. Can be a numeric value, or one of the predefined strings "wrap_content" or "match_parent".

#### width

- `Optional` **width**: `number` | `"wrap_content"` | `"match_parent"`

  Specifies the width of the element. Can be a numeric value, or one of the predefined strings "wrap_content" or "match_parent".
```

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

### Opening URI with clickAction OPEN_URI

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

Use the special `clickAction` value `"OPEN_URI"` to open a specified URI. This requires `clickActionData` to contain a `uri` property, which can be a web URL or an app deep link.

```javascript
<FlexWidget clickAction="OPEN_URI" clickActionData={{ uri: 'https://google.com' }}>
  ...
</FlexWidget>
```

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

### AndroidManifest.xml Configuration

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

Register the widget configuration activity in the AndroidManifest.xml file with the appropriate intent filter.

```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>
```

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

### Java Widget Provider Class

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

Create a Java class that extends RNWidgetProvider to define your widget. The class name will be used to reference the widget.

```java
package com.yourapppackage.widget;  

import com.reactnativeandroidwidget.RNWidgetProvider;  

public class Hello extends RNWidgetProvider {  
}
```

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

### Java Widget Configuration Activity

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

Extend RNWidgetConfigurationActivity to create a custom configuration activity in Java.

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

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

### borderStyle

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

Sets the style of the border. Accepts 'solid', 'dotted', or 'dashed'.

```APIDOC
## borderStyle

### Description
Sets the style of the border. Accepts 'solid', 'dotted', or 'dashed'.

### Type
`"solid"` | `"dotted"` | `"dashed"`

### Inherited From
CommonStyleProps.borderStyle
```

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

### WidgetInfo Interface

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

This snippet details the properties available within the WidgetInfo interface.

```APIDOC
## Interface: WidgetInfo

### Properties

#### widgetName

*   **widgetName** : `string`
    Name of the widget

* * *

#### widgetId

*   **widgetId** : `number`
    Internal id of the widget

* * *

#### height

*   **height** : `number`
    Height of the widget

* * *

#### width

*   **width** : `number`
    Width of the widget

* * *

#### screenInfo

*   **screenInfo** : `ScreenInfo`
    Information about the device
```

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

### Kotlin Widget Configuration Activity

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

Extend RNWidgetConfigurationActivity to create a custom configuration activity in Kotlin.

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

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

### IconWidget

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

A simple widget component for displaying icons. It accepts icon widget properties and returns null, indicating it's a presentational component.

```APIDOC
## IconWidget

### Description
A basic widget component specifically designed for displaying icons. It takes icon widget properties as input.

### Parameters
#### Destructured Parameters
- **(_) ** (`IconWidgetProps`) - The properties required for configuring the IconWidget.
```

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

### Widget Interface Properties

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

Defines the structure and properties for configuring a widget. This includes basic identification, sizing, display attributes, feature flags, update intervals, and package name customization.

```APIDOC
## Interface: Widget

### Properties

- **name** (string) - Required - Name of the widget which will be used to reference it in code.
- **minWidth** (`${number}dp`) - Required - Minimum width of the widget.
- **minHeight** (`${number}dp`) - Required - Minimum height of the widget.
- **label** (string) - Optional - Label that will be shown in the widget picker.
- **description** (string) - Optional - Description that will be shown in the widget picker.
- **targetCellWidth** (number) - Optional - Target cell width for the widget.
- **targetCellHeight** (number) - Optional - Target cell height for the widget.
- **maxResizeWidth** (`${number}dp`) - Optional - Maximum resize width for the widget.
- **maxResizeHeight** (`${number}dp`) - Optional - Maximum resize height for the widget.
- **previewImage** (`./${string}` | `../${string}`) - Optional - Path to the preview image for the widget.
- **resizeMode** ("none" | "horizontal" | "vertical" | "horizontal|vertical") - Optional - Defines how the widget can be resized.
- **widgetFeatures** ("reconfigurable" | "reconfigurable|configuration_optional") - Optional - Specifies if the widget is configurable and how its configuration is handled.
- **updatePeriodMillis** (number) - Optional - How often the widget should be updated, in milliseconds. Default is 0 (no automatic updates). Minimum is 1,800,000 (30 minutes).
- **packageName** (string) - Optional - Custom Java package name for the widget's AppWidgetProvider. It must start with the actual app's package name. Default is "<app-package-name>.widget".
```

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

### Basic IconWidget Usage

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

Demonstrates how to use the IconWidget to display an icon within a FlexWidget. Ensure you import FlexWidget and IconWidget from 'react-native-android-widget'.

```javascript
import { FlexWidget, IconWidget } from 'react-native-android-widget';  
  
export function MyWidget() {
  return (  
    <FlexWidget>
      <IconWidget font="material" size={36} icon="play_arrow" />  
    </FlexWidget>  
  );
}

```

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

### BackgroundStyleProps

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

Defines the properties for styling the background of a widget. This includes setting a solid background color or a gradient with specified colors and orientation.

```APIDOC
## Interface: BackgroundStyleProps

### Description

Properties for styling the background of a widget.

### Properties

#### backgroundColor

- **backgroundColor** (string) - Optional - Specifies the background color of the widget. Accepts hex color codes (e.g., `#ffffff`) or RGBA values (e.g., `rgba(255, 255, 255, 1)`).

#### backgroundGradient

- **backgroundGradient** (object) - Optional - Defines a gradient background for the widget.
  - **from** (ColorProp) - The starting color of the gradient.
  - **to** (ColorProp) - The ending color of the gradient.
  - **orientation** (string) - Optional - The direction of the gradient. Possible values include: "TOP_BOTTOM", "TR_BL", "RIGHT_LEFT", "BR_TL", "BOTTOM_TOP", "BL_TR", "LEFT_RIGHT", "TL_BR".
```

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

### Register Widget Configuration Screen (index.ts)

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

Register the widget configuration screen in your app's main entry file. This ensures the screen is available when a configurable widget is added or reconfigured.

```typescript
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);
```

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

### OPEN_URI Click Action with Data

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

For 'OPEN_URI' clickAction, provide clickActionData containing a 'uri' property. This can be a web URL or an app deep link.

```typescript
"OPEN_URI"
```

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

### Kotlin Widget Provider Class

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

Create a Kotlin class that extends RNWidgetProvider to define your widget. The class name will be used to reference the widget.

```kotlin
package com.yourapppackage.widget  

import com.reactnativeandroidwidget.RNWidgetProvider  

class Hello : RNWidgetProvider() {
}
```

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

### Add Widget Receiver to AndroidManifest.xml

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

Add this receiver to your AndroidManifest.xml to handle widget-related system events and custom actions. Ensure `android:name` reflects the correct package structure for your widget provider class.

```xml
<manifest ...>
  ...
  <application
      android:name=".MainApplication"
      ...>

      <activity
          android:name=".MainActivity"
          ...>
      </activity>

      <service
          android:name="com.reactnativeandroidwidget.RNWidgetCollectionService"
          ... />

      <receiver
          android:name=".widget.Hello"
          android:exported="false"
          android:label="My Hello Widget">
          <intent-filter>
              <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
              <action android:name="com.yourapppackage.WIDGET_CLICK" />
          </intent-filter>
          <meta-data
              android:name="android.appwidget.provider"
              android:resource="@xml/widgetprovider_hello" />
      </receiver>
  </application>
</manifest>
```

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

### IconWidgetStyle Properties

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

Details the optional properties of the IconWidgetStyle interface, including borderStyle and rotation, and their inherited properties.

```APIDOC
## IconWidgetStyle

### Description

Defines the style properties for an icon widget.

### Properties

#### borderStyle

- `Optional` **borderStyle** : `"solid"` | `"dotted"` | `"dashed"`
  Inherited from CommonStyleProps.borderStyle.

#### rotation

- `Optional` **rotation** : `number`
  Inherited from CommonStyleProps.rotation.
```

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

### BorderStyleProps

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

Defines the properties for styling borders. All properties are optional.

```APIDOC
## Interface: BorderStyleProps

### Description

This interface defines the style properties for borders in React Native Android Widget. It allows for granular control over border width, color, and radius.

### Properties

#### borderWidth

- **borderWidth** (number) - Optional - Sets the width of all four borders.

#### borderTopWidth

- **borderTopWidth** (number) - Optional - Sets the width of the top border.

#### borderBottomWidth

- **borderBottomWidth** (number) - Optional - Sets the width of the bottom border.

#### borderLeftWidth

- **borderLeftWidth** (number) - Optional - Sets the width of the left border.

#### borderRightWidth

- **borderRightWidth** (number) - Optional - Sets the width of the right border.

#### borderColor

- **borderColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional - Sets the color of all four borders.

#### borderTopColor

- **borderTopColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional - Sets the color of the top border.

#### borderBottomColor

- **borderBottomColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional - Sets the color of the bottom border.

#### borderLeftColor

- **borderLeftColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional - Sets the color of the left border.

#### borderRightColor

- **borderRightColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional - Sets the color of the right border.

#### borderRadius

- **borderRadius** (number) - Optional - Sets the radius for all four corners of the border.

#### borderTopLeftRadius

- **borderTopLeftRadius** (number) - Optional - Sets the radius for the top-left corner of the border.

#### borderTopRightRadius

- **borderTopRightRadius** (number) - Optional - Sets the radius for the top-right corner of the border.

#### borderBottomLeftRadius

- **borderBottomLeftRadius** (number) - Optional - Sets the radius for the bottom-left corner of the border.

#### borderBottomRightRadius

- **borderBottomRightRadius** (number) - Optional - Sets the radius for the bottom-right corner of the border.

#### borderStyle

- **borderStyle** (`"solid"` | `"dotted"` | `"dashed"`) - Optional - Sets the style of the border (solid, dotted, or dashed).
```

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

### TextWidget

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

A widget component for displaying text. It accepts text widget properties and returns null, signifying its role as a text display element.

```APIDOC
## TextWidget

### Description
A widget component designed for displaying text content. It accepts text widget properties and is intended for textual presentation.

### Parameters
#### Destructured Parameters
- **(_) ** (`TextWidgetProps`) - The properties required for configuring the TextWidget.
```

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

### ImageWidget

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

A widget component for displaying images. It accepts image widget properties and returns null, signifying its role as a display element.

```APIDOC
## ImageWidget

### Description
A widget component dedicated to displaying images. It accepts image widget properties and is intended for visual presentation.

### Parameters
#### Destructured Parameters
- **(_) ** (`ImageWidgetProps`) - The properties required for configuring the ImageWidget.
```

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

### Register Widget Configuration Screen (Expo index.ts)

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

Register the widget configuration screen and task handler in your Expo app's entry file. This is an alternative to the standard `index.js` registration.

```typescript
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);
```

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

### ListWidgetStyle Properties

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

This snippet details the available properties for styling a ListWidgetStyle. These properties control margins, dimensions, background color or gradient, and various border properties.

```APIDOC
## Interface: ListWidgetStyle

### Properties

- **margin** (Optional number): Inherited from MarginStyleProps.
- **marginHorizontal** (Optional number): Inherited from MarginStyleProps.
- **marginVertical** (Optional number): Inherited from MarginStyleProps.
- **marginTop** (Optional number): Inherited from MarginStyleProps.
- **marginBottom** (Optional number): Inherited from MarginStyleProps.
- **marginLeft** (Optional number): Inherited from MarginStyleProps.
- **marginRight** (Optional number): Inherited from MarginStyleProps.
- **height** (Optional number | "wrap_content" | "match_parent"): Inherited from SizeStyleProps.
- **width** (Optional number | "wrap_content" | "match_parent"): Inherited from SizeStyleProps.
- **backgroundColor** (Optional #string | rgba(number, number, number, number)): Inherited from BackgroundStyleProps.
- **backgroundGradient** (Optional Object): Inherited from BackgroundStyleProps.
  - **from** (ColorProp)
  - **to** (ColorProp)
  - **orientation** ("TOP_BOTTOM" | "TR_BL" | "RIGHT_LEFT" | "BR_TL" | "BOTTOM_TOP" | "BL_TR" | "LEFT_RIGHT" | "TL_BR")
- **borderBottomColor** (Optional #string | rgba(number, number, number, number)): Inherited from Omit.borderBottomColor.
- **borderLeftColor** (Optional #string | rgba(number, number, number, number)): Inherited from Omit.borderLeftColor.
- **borderRightColor** (Optional #string | rgba(number, number, number, number)): Inherited from Omit.borderRightColor.
- **borderStyle** (Optional "solid" | "dotted" | "dashed"): Inherited from Omit.borderStyle.
- **borderTopColor** (Optional #string | rgba(number, number, number, number)): Inherited from Omit.borderTopColor.
- **borderColor** (Optional #string | rgba(number, number, number, number)): Inherited from Omit.borderColor.
- **borderWidth** (Optional number): Inherited from Omit.borderWidth.
- **borderTopWidth** (Optional number): Inherited from Omit.borderTopWidth.
- **borderLeftWidth** (Optional number): Inherited from Omit.borderLeftWidth.
- **borderRightWidth** (Optional number): Inherited from Omit.borderRightWidth.
- **borderBottomWidth** (Optional number): Inherited from Omit.borderBottomWidth.
```

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

### CommonStyleProps

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

The CommonStyleProps interface combines properties from MarginStyleProps, PaddingStyleProps, SizeStyleProps, BackgroundStyleProps, and BorderStyleProps, providing a comprehensive set of styling options for widgets.

```APIDOC
## Interface: CommonStyleProps

### Description
This interface aggregates common styling properties for widgets, including margin, padding, size, background, and border properties. It inherits from several specialized style interfaces.

### Properties

#### Margin Properties (Inherited from MarginStyleProps)
- **margin** (number) - Optional
- **marginHorizontal** (number) - Optional
- **marginVertical** (number) - Optional
- **marginTop** (number) - Optional
- **marginBottom** (number) - Optional
- **marginLeft** (number) - Optional
- **marginRight** (number) - Optional

#### Padding Properties (Inherited from PaddingStyleProps)
- **padding** (number) - Optional
- **paddingHorizontal** (number) - Optional
- **paddingVertical** (number) - Optional
- **paddingTop** (number) - Optional
- **paddingBottom** (number) - Optional
- **paddingLeft** (number) - Optional
- **paddingRight** (number) - Optional

#### Size Properties (Inherited from SizeStyleProps)
- **height** (number | "wrap_content" | "match_parent") - Optional
- **width** (number | "wrap_content" | "match_parent") - Optional

#### Background Properties (Inherited from BackgroundStyleProps)
- **backgroundColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional
- **backgroundGradient** (Object) - Optional
  - **from** (ColorProp)
  - **to** (ColorProp)
  - **orientation** ("TOP_BOTTOM" | "TR_BL" | "RIGHT_LEFT" | "BR_TL" | "BOTTOM_TOP" | "BL_TR" | "LEFT_RIGHT" | "TL_BR")

#### Border Properties (Inherited from BorderStyleProps)
- **borderWidth** (number) - Optional
- **borderTopWidth** (number) - Optional
- **borderBottomWidth** (number) - Optional
- **borderLeftWidth** (number) - Optional
- **borderRightWidth** (number) - Optional
- **borderColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional
- **borderTopColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional
- **borderBottomColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional
- **borderLeftColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional
- **borderRightColor** (`#${string}` | `rgba(${number}, ${number}, ${number}, ${number})`) - Optional
- **borderRadius** (number) - Optional
- **borderTopLeftRadius** (number) - Optional
- **borderTopRightRadius** (number) - Optional
- **borderBottomLeftRadius** (number) - Optional
- **borderBottomRightRadius** (number) - Optional

### Hierarchy
- `MarginStyleProps`
- `PaddingStyleProps`
- `SizeStyleProps`
- `BackgroundStyleProps`
- `BorderStyleProps`
- `OtherStyleProps`
↳ **`CommonStyleProps`**
↳↳ `FlexWidgetStyle`
↳↳ `IconWidgetStyle`
↳↳ `OverlapWidgetStyle`
↳↳ `TextWidgetStyle`
```

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

### ScreenInfo Properties

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

This interface defines properties for retrieving screen dimensions and density, useful for responsive UI design in React Native Android.

```APIDOC
## Interface: ScreenInfo

### 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.
```

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

### registerWidgetConfigurationScreen

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

Registers a React component to handle the widget configuration screen. This function is crucial for allowing users to customize widget settings.

```APIDOC
## registerWidgetConfigurationScreen

### Description
Registers a React component that will be used to handle the widget configuration screen. This allows users to customize widget settings before adding them.

### Parameters
#### Path Parameters
- **WidgetConfigurationScreenComponent** (`WidgetConfigurationScreen`) - Required - The React component to register for widget configuration.
```

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

### Add Custom Fonts for Widgets

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

Include paths to any custom fonts used in your widgets within the assets directory. These fonts will be available for your widget's styling.

```text
assets/fonts/Inter.ttf
```

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

### Requesting Widget Update with Dark Mode Variants

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

Initiate widget updates from your application by calling `requestWidgetUpdate`. Pass a `renderWidget` callback that returns an object with `light` and `dark` render trees to specify theme-specific appearances.

```typescript
import React from 'react';
import { requestWidgetUpdate } from 'react-native-android-widget';
import { Widget } from '../widgets/Widget';

function onSomeEvent() {
  requestWidgetUpdate({
    widgetName: 'Counter',
    renderWidget: () => ({
      light: <Widget theme="light" />,
      dark: <Widget theme="dark" />,
    }),
  });
}
```

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

### Registering Widget Task Handler with Dark Mode Support

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

Implement dark mode by providing separate `light` and `dark` React elements to `props.renderWidget` within a widget task handler. This ensures the widget adapts to the system's current theme.

```typescript
import React from 'react';
import { WidgetTaskHandlerProps } from 'react-native-android-widget';
import { Widget } from '../../widgets/Widget';

export async function widgetTaskHandler(props: WidgetTaskHandlerProps) {
  switch (props.widgetAction) {
    case 'WIDGET_ADDED':
    case 'WIDGET_UPDATED':
      // props.renderWidget(<Widget />);
      props.renderWidget({
        light: <Widget theme="light" />,
        dark: <Widget theme="dark" />,
      });
      break;
      // handle other actions
  }
}
```

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

### FlexWidget

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

A flexible widget component that can be configured with various properties. It is designed to adapt to different content and styling needs.

```APIDOC
## FlexWidget

### Description
A versatile widget component that allows for flexible layout and content arrangement. It accepts a set of properties to define its appearance and behavior.

### Parameters
#### Destructured Parameters
- **(props)** (`FlexWidgetProps`) - The properties required for configuring the FlexWidget.
```

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

### WidgetPreviewProps

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

Props for the WidgetPreview component, used to configure widget rendering and behavior.

```APIDOC
## Interface: WidgetPreviewProps

### Properties

#### renderWidget

- **Type**: `(props: { width: number; height: number }) => Element`
- **Description**: Callback function that will be called by `WidgetPreview` to generate the widget UI.
  - **Parameters**:
    - `props` (Object) - An object containing widget dimensions.
      - `props.width` (number) - The width of the widget.
      - `props.height` (number) - The height of the widget.
  - **Returns**: `Element` - The rendered widget UI.

#### height

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

#### width

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

#### onClick (Optional)

- **Type**: `(props: OnClick) => void`
- **Description**: Callback function that will be called when clicked on a clickable area of the widget.
  - **Parameters**:
    - `props` (OnClick) - An object representing the click event.
  - **Returns**: `void`

#### showBorder (Optional)

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

#### highlightClickableAreas (Optional)

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

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

### Update package.json for Expo

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

Modify the 'main' field in `package.json` to point to your custom entry file (e.g., `index.ts`) when using Expo.

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

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

### ClickActionProps Interface

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

Defines the properties for click actions and accessibility on widgets. This interface allows for custom actions, opening URIs, opening the app, and setting accessibility labels for screen readers.

```APIDOC
## Interface: ClickActionProps

### Properties

#### clickAction

- **`clickAction`** (string) - Optional - A string that defines an action emitted when the widget is clicked. Special values like `"OPEN_APP"` execute actions in the background without requiring `clickActionData`. `"OPEN_URI"` requires `clickActionData` containing a `uri`.

#### clickActionData

- **`clickActionData`** (Record<string, unknown>) - Optional - Additional data passed when the widget is clicked. For `"OPEN_URI"`, this must contain `{ uri: 'some-uri' }`.

#### accessibilityLabel

- **`accessibilityLabel`** (string) - Optional - An accessibility label for screen readers. Can be applied to the root component or specific clickable components to describe the widget or a particular clickable area.
```

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

### ListWidget

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

A widget component designed to display lists of items. It accepts list widget properties and is suitable for presenting scrollable content.

```APIDOC
## ListWidget

### Description
A widget component optimized for displaying lists of items. It accepts list widget properties and can be used for scrollable content.

### Parameters
#### Destructured Parameters
- **(props)** (`ListWidgetProps`) - The properties required for configuring the ListWidget.
```

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

### Displaying a Local Image with ImageWidget

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

Use this snippet to display a local image asset within your widget. Ensure the image path is correctly specified relative to the widget's context.

```javascript
import { FlexWidget, ImageWidget } from 'react-native-android-widget';  
  
export function MyWidget() {  
  return (  
    <FlexWidget>  
      <ImageWidget  
        image={require('../assets/image-file.jpg')}
        imageWidth={88}  
        imageHeight={88}  
      />  
    </FlexWidget>  
  );
}
```

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

### ListWidgetProps Interface

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

Defines the properties that can be passed to a List Widget.

```APIDOC
## Interface: ListWidgetProps

### Properties

#### children

- `Optional` **children** : `any`
  - Description: Represents the content to be rendered within the widget.

#### style

- `Optional` **style** : `ListWidgetStyle`
  - Description: Defines the visual styling of the list widget.
```