feat: accessibility/talkback support

Author: sAleksovski

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## Added
+
+- Accessibility (TalkBack) support
+
 ## [0.19.0] - 2026-01-11
 
 ## Added

android/src/main/java/com/reactnativeandroidwidget/RNWidget.java

@@ -76,6 +76,10 @@ public void drawWidget(int widgetId) throws Exception {
         Uri bitmapUri = saveBitmapToDisk(widgetId, "light", bitmap);
         remoteWidgetView.setImageViewUri(R.id.rn_widget_image_light, bitmapUri);
 
+        if (widgetWithViews.getRootAccessibilityLabel() != null) {
+            remoteWidgetView.setContentDescription(R.id.rn_widget_clickable_container, widgetWithViews.getRootAccessibilityLabel());
+        }
+
         if (dark != null) {
             WidgetWithViews darkWidgetWithViews = WidgetFactory.buildWidgetFromRoot(
                 appContext,
@@ -175,6 +179,10 @@ private void addClickableArea(RemoteViews widgetView, ViewGroup rootWidget, Clic
 
         clickableRemoteView.setInt(R.id.rn_widget_clickable_area, "setMinimumHeight", offsetViewBounds.height());
 
+        if (clickableView.getAccessibilityLabel() != null) {
+            clickableRemoteView.setContentDescription(R.id.rn_widget_clickable_area, clickableView.getAccessibilityLabel());
+        }
+
         registerClickTask(widgetId, clickableView, clickableRemoteView, R.id.rn_widget_clickable_area);
 
         widgetView.addView(R.id.rn_widget_clickable_container, clickableRemoteView);
@@ -258,6 +266,12 @@ private Intent createCollectionRemoteAdapterIntent(int widgetId, int collectionI
             bundle.putInt("imageWidth", collectionViewItem.getBitmap().getWidth());
             bundle.putString("lightImageName", RNWidgetCollectionService.getImageName(widgetId, collectionId, i, "light"));
             bundle.putString("darkImageName", RNWidgetCollectionService.getImageName(widgetId, collectionId, i, "dark"));
+            
+            // Add item accessibility label if available
+            if (collectionViewItem.getItemAccessibilityLabel() != null) {
+                bundle.putString("itemAccessibilityLabel", collectionViewItem.getItemAccessibilityLabel());
+            }
+            
             collectionItemsBundle.add(bundle);
 
             ArrayList<Bundle> clickableAreas = new ArrayList<>();
@@ -275,6 +289,11 @@ private Intent createCollectionRemoteAdapterIntent(int widgetId, int collectionI
                 collectionViewMap.putInt("width", offsetViewBounds.width());
                 collectionViewMap.putString("clickAction", clickableView.getClickAction());
                 collectionViewMap.putBundle("clickActionData", Arguments.toBundle(clickableView.getClickActionData()));
+                
+                // Add clickable area accessibility label if available
+                if (clickableView.getAccessibilityLabel() != null) {
+                    collectionViewMap.putString("accessibilityLabel", clickableView.getAccessibilityLabel());
+                }
 
                 clickableAreas.add(collectionViewMap);
             }

android/src/main/java/com/reactnativeandroidwidget/RNWidgetCollectionService.java

@@ -77,6 +77,13 @@ public RemoteViews getViewAt(int position) {
         Uri darkImageUri = RNWidgetImageProvider.getImageUri(mContext, bundle.getString("darkImageName"));
         listItemView.setImageViewUri(R.id.rn_widget_list_item_dark, darkImageUri);
 
+        // Set item accessibility label on ImageViews if available
+        if (bundle.getString("itemAccessibilityLabel", null) != null) {
+            String itemAccessibilityLabel = bundle.getString("itemAccessibilityLabel");
+            listItemView.setContentDescription(R.id.rn_widget_list_item_light, itemAccessibilityLabel);
+            listItemView.setContentDescription(R.id.rn_widget_list_item_dark, itemAccessibilityLabel);
+        }
+
         // Set a fill-intent which will be used to fill-in the pending intent template
         // which is set on the collection view in RNWidget.
         if (bundle.getString("clickAction", null) != null) {
@@ -109,6 +116,11 @@ private void addClickableArea(RemoteViews widgetView, Bundle clickableArea, int
 
         clickableRemoteView.setInt(R.id.rn_widget_clickable_area, "setMinimumHeight", clickableArea.getInt("height"));
 
+        // Set accessibility label on clickable area if available
+        if (clickableArea.getString("accessibilityLabel", null) != null) {
+            clickableRemoteView.setContentDescription(R.id.rn_widget_clickable_area, clickableArea.getString("accessibilityLabel"));
+        }
+
         PendingIntent pendingIntent = createPendingIntent(clickableArea);
         clickableRemoteView.setOnClickPendingIntent(R.id.rn_widget_clickable_area, pendingIntent);
 

android/src/main/java/com/reactnativeandroidwidget/builder/ClickableView.java

@@ -9,12 +9,18 @@ public class ClickableView implements Comparable<ClickableView> {
     private final View view;
     private final String clickAction;
     private final ReadableMap clickActionData;
+    private final String accessibilityLabel;
 
     public ClickableView(String id, View view, String clickAction, ReadableMap clickActionData) {
+        this(id, view, clickAction, clickActionData, null);
+    }
+
+    public ClickableView(String id, View view, String clickAction, ReadableMap clickActionData, String accessibilityLabel) {
         this.id = id;
         this.view = view;
         this.clickAction = clickAction;
         this.clickActionData = clickActionData;
+        this.accessibilityLabel = accessibilityLabel;
     }
 
     public String getId() {
@@ -33,6 +39,10 @@ public ReadableMap getClickActionData() {
         return clickActionData;
     }
 
+    public String getAccessibilityLabel() {
+        return accessibilityLabel;
+    }
+
     @Override
     public int compareTo(ClickableView o) {
         return this.id.compareTo(o.getId());

android/src/main/java/com/reactnativeandroidwidget/builder/CollectionView.java

@@ -61,18 +61,25 @@ public void buildChildren(ReactApplicationContext appContext) throws Exception {
             List<ClickableView> clickableViews = widgetWithViews.getClickableViews();
             Bitmap bitmap = getBitmap(rootView.getChildAt(0));
 
+            // Extract item accessibility label from original config
+            String itemAccessibilityLabel = null;
+            if (configClone.getMap("props").hasKey("accessibilityLabel")) {
+                itemAccessibilityLabel = configClone.getMap("props").getString("accessibilityLabel");
+            }
+
             if (configClone.getMap("props").hasKey("clickAction")) {
                 renderedViews.add(
                     new CollectionViewItem(
                         rootView,
                         bitmap,
                         clickableViews,
                         configClone.getMap("props").getString("clickAction"),
-                        configClone.getMap("props").getMap("clickActionData")
+                        configClone.getMap("props").getMap("clickActionData"),
+                        itemAccessibilityLabel
                     )
                 );
             } else {
-                renderedViews.add(new CollectionViewItem(rootView, bitmap, clickableViews));
+                renderedViews.add(new CollectionViewItem(rootView, bitmap, clickableViews, null, null, itemAccessibilityLabel));
             }
         }
     }

android/src/main/java/com/reactnativeandroidwidget/builder/CollectionViewItem.java

@@ -3,6 +3,8 @@
 import android.graphics.Bitmap;
 import android.view.ViewGroup;
 
+import androidx.annotation.Nullable;
+
 import com.facebook.react.bridge.Arguments;
 import com.facebook.react.bridge.ReadableMap;
 
@@ -14,8 +16,13 @@ public class CollectionViewItem {
     private final List<ClickableView> clickableViews;
     private final String clickAction;
     private final ReadableMap clickActionData;
+    private final String itemAccessibilityLabel;
 
     public CollectionViewItem(ViewGroup view, Bitmap bitmap, List<ClickableView> clickableViews, String clickAction, ReadableMap clickActionData) {
+        this(view, bitmap, clickableViews, clickAction, clickActionData, null);
+    }
+
+    public CollectionViewItem(ViewGroup view, Bitmap bitmap, List<ClickableView> clickableViews, String clickAction, ReadableMap clickActionData, @Nullable String itemAccessibilityLabel) {
         this.view = view;
         this.bitmap = bitmap;
         this.clickableViews = clickableViews;
@@ -25,10 +32,11 @@ public CollectionViewItem(ViewGroup view, Bitmap bitmap, List<ClickableView> cli
         } else {
             this.clickActionData = clickActionData;
         }
+        this.itemAccessibilityLabel = itemAccessibilityLabel;
     }
 
     public CollectionViewItem(ViewGroup view, Bitmap bitmap, List<ClickableView> clickableViews) {
-        this(view, bitmap, clickableViews, null, null);
+        this(view, bitmap, clickableViews, null, null, null);
     }
 
     public ViewGroup getView() {
@@ -50,4 +58,9 @@ public String getClickAction() {
     public ReadableMap getClickActionData() {
         return clickActionData;
     }
+
+    @Nullable
+    public String getItemAccessibilityLabel() {
+        return itemAccessibilityLabel;
+    }
 }

android/src/main/java/com/reactnativeandroidwidget/builder/WidgetFactory.java

@@ -29,16 +29,26 @@
 public class WidgetFactory {
     private final List<ClickableView> clickableViews;
     private final List<CollectionView> collectionViews;
+    private String rootAccessibilityLabel;
 
     private WidgetFactory() {
         this.clickableViews = new ArrayList<>();
         this.collectionViews = new ArrayList<>();
+        this.rootAccessibilityLabel = null;
     }
 
     public static WidgetWithViews buildWidgetFromRoot(ReactApplicationContext context, ReadableMap config, int width, int height) throws Exception {
         WidgetFactory widgetFactory = new WidgetFactory();
 
-        View view = widgetFactory.buildWidget(context, widgetFactory.getRootConfig(config, width, height), "0");
+        ReadableMap configClone = Arguments.makeNativeMap(config.toHashMap());
+
+        ReadableMap rootConfig = widgetFactory.getRootConfig(config, width, height);
+
+        if (configClone.hasKey("props") && configClone.getMap("props").hasKey("accessibilityLabel")) {
+            widgetFactory.rootAccessibilityLabel = configClone.getMap("props").getString("accessibilityLabel");
+        }
+
+        View view = widgetFactory.buildWidget(context, rootConfig, "0");
 
         for (int i = 0; i < widgetFactory.collectionViews.size(); i++) {
             widgetFactory.collectionViews.get(i).buildChildren(context);
@@ -47,7 +57,7 @@ public static WidgetWithViews buildWidgetFromRoot(ReactApplicationContext contex
         ResourceUtils.clear();
 
         Collections.sort(widgetFactory.clickableViews);
-        return new WidgetWithViews(view, widgetFactory.clickableViews, widgetFactory.collectionViews);
+        return new WidgetWithViews(view, widgetFactory.clickableViews, widgetFactory.collectionViews, widgetFactory.rootAccessibilityLabel);
     }
 
     @NonNull
@@ -81,12 +91,17 @@ private View buildWidget(ReactApplicationContext context, ReadableMap config, St
         }
 
         if (config.getMap("props").hasKey("clickAction")) {
+            String accessibilityLabel = null;
+            if (config.getMap("props").hasKey("accessibilityLabel")) {
+                accessibilityLabel = config.getMap("props").getString("accessibilityLabel");
+            }
             clickableViews.add(
                 new ClickableView(
                     id,
                     view,
                     config.getMap("props").getString("clickAction"),
-                    config.getMap("props").getMap("clickActionData")
+                    config.getMap("props").getMap("clickActionData"),
+                    accessibilityLabel
                 )
             );
         }

android/src/main/java/com/reactnativeandroidwidget/builder/WidgetWithViews.java

@@ -2,17 +2,25 @@
 
 import android.view.View;
 
+import androidx.annotation.Nullable;
+
 import java.util.List;
 
 public class WidgetWithViews {
     private final View rootView;
     private final List<ClickableView> clickableViews;
     private final List<CollectionView> collectionViews;
+    private final String rootAccessibilityLabel;
 
     WidgetWithViews(View rootView, List<ClickableView> clickableViews, List<CollectionView> collectionViews) {
+        this(rootView, clickableViews, collectionViews, null);
+    }
+
+    WidgetWithViews(View rootView, List<ClickableView> clickableViews, List<CollectionView> collectionViews, @Nullable String rootAccessibilityLabel) {
         this.rootView = rootView;
         this.clickableViews = clickableViews;
         this.collectionViews = collectionViews;
+        this.rootAccessibilityLabel = rootAccessibilityLabel;
     }
 
     public View getRootView() {
@@ -26,4 +34,9 @@ public List<ClickableView> getClickableViews() {
     public List<CollectionView> getCollectionViews() {
         return collectionViews;
     }
+
+    @Nullable
+    public String getRootAccessibilityLabel() {
+        return rootAccessibilityLabel;
+    }
 }

docs/docs/demo.md

@@ -13,10 +13,18 @@ You can download the demo app with the example widgets from the [Releases Page](
 
 ## List Widget Preview
 
+This widget is accessible
+
 ![List Widget Preview](../../example-expo/assets/widget-preview/list.png)
 
+## Dark Mode Widget Preview
+
+![Dark Mode Widget Preview](../../example-expo/assets/widget-preview/darkmode.png)
+
 ## Resizable Music Widget Preview
 
+This widget is accessible
+
 ![Resizable Music Widget Preview](../../example-expo/assets/widget-preview/resizable.png)
 
 ## Rotated Widget Preview

docs/docs/tutorial/congratulations.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 10
 ---
 
 # Congratulations!