react-native-navigation 8.8.6 → 8.8.7-snapshot.2601

package/android/src/main/java/com/reactnativenavigation/customrow/BottomTabsCustomRowLayout.kt

@@ -0,0 +1,139 @@
+package com.reactnativenavigation.customrow
+
+import android.app.Activity
+import android.os.Build
+import android.util.TypedValue
+import android.view.View
+import android.view.ViewGroup
+import com.reactnativenavigation.views.bottomtabs.BottomTabs
+
+/**
+ * Resolves how the floating custom row should anchor and whether the bottom
+ * system-bar inset belongs inside the row or was already applied by RNN's
+ * [com.reactnativenavigation.viewcontrollers.bottomtabs.BottomTabsController].
+ *
+ * On most devices (including Pixel with gesture/3-button nav) RNN pads the
+ * bottom-tabs controller by `systemBars().bottom`, so the native bar already
+ * sits above the nav area — adding the same inset again creates a visible gap.
+ *
+ * With edge-to-edge (API 35+ theme opt-in) content can extend behind the nav
+ * bar; the row must pin to the overlay host bottom and reserve inset inside.
+ */
+internal object BottomTabsCustomRowLayout {
+
+    enum class AnchorMode {
+        /** Native bar bottom is already above system bars (RNN bottom padding). */
+        NATIVE_BAR_ABOVE_SYSTEM_BARS,
+        /** Row extends to the host bottom; inset is applied inside the row. */
+        EDGE_TO_EDGE,
+    }
+
+    data class Placement(
+        val anchorMode: AnchorMode,
+        /** Inset applied inside the row for cell/chrome layout (0 when native bar already cleared it). */
+        val rowSafeBottomInsetPx: Int,
+        val left: Int,
+        val top: Int,
+        val width: Int,
+        val height: Int,
+    )
+
+    fun resolvePlacement(
+        activity: Activity,
+        row: BottomTabsCustomRow,
+        bottomTabs: BottomTabs,
+        overlayHost: ViewGroup,
+        navBarInsetPx: Int,
+    ): Placement? {
+        val nativeHeight = bottomTabs.height
+        if (nativeHeight <= 0) return null
+
+        val horizontalMargin = row.effectiveHorizontalMarginPx()
+        val bottomMargin = row.effectiveBottomMarginPx()
+
+        val tabLeftInHost = tabLeftRelativeToHost(bottomTabs, overlayHost)
+        val tabRightInHost = tabLeftInHost + bottomTabs.width
+
+        // Row is hosted on `android.R.id.content`; anchor to `BottomTabs` bottom
+        // (above RNN's nav-bar padding). Never use decor.height — that draws over
+        // the system navigation buttons.
+        val anchorMode = resolveAnchorMode(activity, bottomTabs, overlayHost, navBarInsetPx)
+        val rowSafeBottom = 0
+
+        val contentHeight = row.effectiveContentHeightPx(nativeHeight)
+        val totalHeight = contentHeight + bottomMargin
+
+        val left = tabLeftInHost + horizontalMargin
+        val width = (tabRightInHost - horizontalMargin) - left
+
+        // RNN already lays out `BottomTabs` above its bottom padding — match that
+        // edge. Do not subtract `navBarInsetPx` again (that was lifting the bar).
+        val bottom = tabBottomRelativeToHost(bottomTabs, overlayHost) - bottomMargin
+        val top = bottom - totalHeight
+
+        return Placement(anchorMode, rowSafeBottom, left, top, width, totalHeight)
+    }
+
+    fun resolveAnchorMode(
+        activity: Activity,
+        bottomTabs: BottomTabs,
+        overlayHost: ViewGroup,
+        @Suppress("UNUSED_PARAMETER") navBarInsetPx: Int,
+    ): AnchorMode {
+        // RNN's bottom-tabs host ends at `android.R.id.content` bottom while the
+        // system nav bar sits below that — never treat "flush with content" as
+        // edge-to-edge or we reserve a phantom inset and leave a white gap.
+        if (!isEdgeToEdgeEnabled(activity)) {
+            return AnchorMode.NATIVE_BAR_ABOVE_SYSTEM_BARS
+        }
+        val decor = activity.window?.decorView ?: return AnchorMode.NATIVE_BAR_ABOVE_SYSTEM_BARS
+        val tolerancePx = dpToPx(activity, 4f)
+        val tabBottomOnScreen = screenBottom(bottomTabs)
+        val decorBottomOnScreen = screenBottom(decor)
+        return if (kotlin.math.abs(tabBottomOnScreen - decorBottomOnScreen) <= tolerancePx) {
+            AnchorMode.EDGE_TO_EDGE
+        } else {
+            AnchorMode.NATIVE_BAR_ABOVE_SYSTEM_BARS
+        }
+    }
+
+    private fun screenBottom(view: android.view.View): Int {
+        val loc = IntArray(2).also(view::getLocationOnScreen)
+        return loc[1] + view.height
+    }
+
+    fun isEdgeToEdgeEnabled(activity: Activity): Boolean {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.VANILLA_ICE_CREAM) {
+            return false
+        }
+        val typedValue = TypedValue()
+        val resolved = activity.theme.resolveAttribute(
+            android.R.attr.windowOptOutEdgeToEdgeEnforcement,
+            typedValue,
+            true
+        )
+        return resolved &&
+            typedValue.type == TypedValue.TYPE_INT_BOOLEAN &&
+            typedValue.data == 0
+    }
+
+    private fun tabLeftRelativeToHost(bottomTabs: BottomTabs, overlayHost: ViewGroup): Int {
+        val tabLoc = IntArray(2).also(bottomTabs::getLocationOnScreen)
+        val hostLoc = IntArray(2).also(overlayHost::getLocationOnScreen)
+        return tabLoc[0] - hostLoc[0]
+    }
+
+    private fun tabBottomRelativeToHost(bottomTabs: BottomTabs, overlayHost: ViewGroup): Int {
+        val tabLoc = IntArray(2).also(bottomTabs::getLocationOnScreen)
+        val hostLoc = IntArray(2).also(overlayHost::getLocationOnScreen)
+        val tabTopInHost = tabLoc[1] - hostLoc[1]
+        return tabTopInHost + bottomTabs.height
+    }
+
+    private fun dpToPx(activity: Activity, dp: Float): Int =
+        TypedValue.applyDimension(
+            TypedValue.COMPLEX_UNIT_DIP,
+            dp,
+            activity.resources.displayMetrics
+        ).toInt()
+}

package/android/src/main/java/com/reactnativenavigation/customrow/BottomTabsCustomRowModule.kt

@@ -0,0 +1,37 @@
+package com.reactnativenavigation.customrow
+
+import android.app.Application
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.module.annotations.ReactModule
+
+/**
+ * RN bridge module that lets JS push the latest `bottomTabs.customRow`
+ * configuration to native. The JS-side `AndroidCustomRowForwarder`
+ * scans `Navigation.setRoot` / `setDefaultOptions` / `mergeOptions`
+ * payloads and calls [configure] whenever it finds a `customRow` block.
+ */
+@ReactModule(name = BottomTabsCustomRowModule.NAME)
+class BottomTabsCustomRowModule(
+    reactContext: ReactApplicationContext,
+) : ReactContextBaseJavaModule(reactContext) {
+
+    init {
+        val app = reactContext.applicationContext as? Application
+        if (app != null) BottomTabsCustomRowAttacher.registerOnce(app)
+    }
+
+    override fun getName(): String = NAME
+
+    @ReactMethod
+    fun configure(config: ReadableMap?) {
+        BottomTabsCustomRowConfigStore.update(BottomTabsCustomRowOptions.fromMap(config))
+        BottomTabsCustomRowAttacher.rescan()
+    }
+
+    companion object {
+        const val NAME = "RNNBottomTabsCustomRowModule"
+    }
+}

package/android/src/main/java/com/reactnativenavigation/customrow/BottomTabsCustomRowOptions.kt

@@ -0,0 +1,68 @@
+package com.reactnativenavigation.customrow
+
+import android.graphics.Color
+import com.facebook.react.bridge.ReadableMap
+
+/**
+ * Mirrors the iOS-side `RNNBottomTabsCustomRowOptions` data shape. All
+ * fields are optional. Defaults are chosen to give an Android equivalent
+ * of the iOS 26 floating glass pill on Android 12+ (RenderEffect blur),
+ * and an opaque material chrome on older versions.
+ */
+data class BottomTabsCustomRowOptions(
+    val height: Float? = null,
+    val backgroundColor: Int? = null,
+    val backgroundEffect: BackgroundEffect? = null,
+    val cornerRadius: Float? = null,
+    val horizontalMargin: Float? = null,
+    val bottomMargin: Float? = null,
+) {
+    enum class BackgroundEffect { Glass, Blur, None }
+
+    companion object {
+        fun fromMap(map: ReadableMap?): BottomTabsCustomRowOptions {
+            if (map == null) return BottomTabsCustomRowOptions()
+            return BottomTabsCustomRowOptions(
+                height = map.optFloat("height"),
+                backgroundColor = map.optColor("backgroundColor"),
+                backgroundEffect = map.optEffect("backgroundEffect"),
+                cornerRadius = map.optFloat("cornerRadius"),
+                horizontalMargin = map.optFloat("horizontalMargin"),
+                bottomMargin = map.optFloat("bottomMargin"),
+            )
+        }
+
+        private fun ReadableMap.optFloat(key: String): Float? {
+            if (!hasKey(key) || isNull(key)) return null
+            return getDouble(key).toFloat()
+        }
+
+        private fun ReadableMap.optColor(key: String): Int? {
+            if (!hasKey(key) || isNull(key)) return null
+            // Color may arrive as a number (Android-style int) or a wrapped
+            // theme-color object. Support both shallowly.
+            return when (getType(key)) {
+                com.facebook.react.bridge.ReadableType.Number -> getInt(key)
+                com.facebook.react.bridge.ReadableType.Map -> {
+                    val sub = getMap(key)
+                    val light = sub?.let { if (it.hasKey("light")) it.getInt("light") else null }
+                    light ?: sub?.let { if (it.hasKey("color")) it.getInt("color") else null }
+                }
+                com.facebook.react.bridge.ReadableType.String -> {
+                    runCatching { Color.parseColor(getString(key)) }.getOrNull()
+                }
+                else -> null
+            }
+        }
+
+        private fun ReadableMap.optEffect(key: String): BackgroundEffect? {
+            if (!hasKey(key) || isNull(key)) return null
+            return when (getString(key)?.lowercase()) {
+                "glass" -> BackgroundEffect.Glass
+                "blur" -> BackgroundEffect.Blur
+                "none" -> BackgroundEffect.None
+                else -> null
+            }
+        }
+    }
+}

package/android/src/main/java/com/reactnativenavigation/options/BottomTabOptions.java

@@ -44,6 +44,7 @@ public class BottomTabOptions {
         options.dotIndicator = DotIndicatorOptions.parse(context, json.optJSONObject("dotIndicator"));
         options.selectTabOnPress = BoolParser.parse(json, "selectTabOnPress");
         options.popToRoot = BoolParser.parse(json, "popToRoot");
+        options.component = ComponentOptions.parse(json.optJSONObject("component"));
 
         return options;
     }
@@ -67,6 +68,7 @@ public class BottomTabOptions {
     public Bool selectTabOnPress = new NullBool();
     public Bool popToRoot = new NullBool();
     public FontOptions font = new FontOptions();
+    public ComponentOptions component = new ComponentOptions();
 
 
     void mergeWith(final BottomTabOptions other) {
@@ -90,6 +92,7 @@ public class BottomTabOptions {
         if (other.dotIndicator.hasValue()) dotIndicator = other.dotIndicator;
         if (other.selectTabOnPress.hasValue()) selectTabOnPress = other.selectTabOnPress;
         if (other.popToRoot.hasValue()) popToRoot = other.popToRoot;
+        if (other.component.hasValue()) component = other.component;
     }
 
     void mergeWithDefault(final BottomTabOptions defaultOptions) {
@@ -113,7 +116,7 @@ public class BottomTabOptions {
         if (!dotIndicator.hasValue()) dotIndicator = defaultOptions.dotIndicator;
         if (!selectTabOnPress.hasValue()) selectTabOnPress = defaultOptions.selectTabOnPress;
         if (!popToRoot.hasValue()) popToRoot = defaultOptions.popToRoot;
-
+        if (!component.hasValue()) component = defaultOptions.component;
     }
 
 }

package/android/src/main/java/com/reactnativenavigation/react/ReactView.java

@@ -16,6 +16,7 @@ import com.facebook.react.ReactApplication;
 import com.facebook.react.ReactHost;
 import com.facebook.react.bridge.ReactContext;
 import com.facebook.react.interfaces.fabric.ReactSurface;
+import com.facebook.react.runtime.ReactSurfaceImpl;
 import com.facebook.react.uimanager.UIManagerHelper;
 import com.facebook.react.uimanager.common.UIManagerType;
 import com.facebook.react.uimanager.events.EventDispatcher;
@@ -71,6 +72,18 @@ public class ReactView extends FrameLayout implements IReactView, Renderable {
         reactSurface.stop();
     }
 
+    /**
+     * Replace the surface's initial props. Useful for components that need to
+     * receive runtime updates from native (e.g. bottom tab item components).
+     * No-op when the underlying surface implementation does not support
+     * runtime prop updates.
+     */
+    public void setProps(Bundle props) {
+        if (reactSurface instanceof ReactSurfaceImpl) {
+            ((ReactSurfaceImpl) reactSurface).updateInitProps(props);
+        }
+    }
+
     public void sendComponentWillStart(ComponentType type) {
         this.post(() -> {
             ReactContext currentReactContext = getReactContext();

package/android/src/main/java/com/reactnativenavigation/react/events/ComponentType.java

@@ -4,7 +4,8 @@ public enum ComponentType {
     Component("Component"),
     Button("TopBarButton"),
     Title("TopBarTitle"),
-    Background("TopBarBackground");
+    Background("TopBarBackground"),
+    BottomTabItem("BottomTabItem");
 
     private String name;
 

package/android/src/main/java/com/reactnativenavigation/viewcontrollers/bottomtabs/BottomTabPresenter.java

@@ -20,7 +20,9 @@ import com.reactnativenavigation.utils.ImageLoadingListenerAdapter;
 import com.reactnativenavigation.utils.LateInit;
 import com.reactnativenavigation.viewcontrollers.viewcontroller.ViewController;
 import com.reactnativenavigation.views.bottomtabs.BottomTabs;
+import com.reactnativenavigation.views.bottomtabs.CustomBottomTabItemView;
 
+import java.util.ArrayList;
 import java.util.List;
 
 public class BottomTabPresenter {
@@ -33,6 +35,7 @@ public class BottomTabPresenter {
     private final LateInit<BottomTabs> bottomTabs = new LateInit<>();
     private final List<ViewController<?>> tabs;
     private final int defaultDotIndicatorSize;
+    private boolean useCustomItemViews;
 
     public BottomTabPresenter(Context context, List<ViewController<?>> tabs, ImageLoader imageLoader,  TypefaceLoader typefaceLoader, Options defaultOptions) {
         this.tabs = tabs;
@@ -53,10 +56,27 @@ public class BottomTabPresenter {
         this.bottomTabs.set(bottomTabs);
     }
 
+    /**
+     * When `true`, tabs whose options declare `bottomTab.component` are
+     * skipped during native icon/text application. The accompanying
+     * `CustomBottomTabItemView` overlay is responsible for visual rendering.
+     */
+    public void setUseCustomItemViews(boolean useCustomItemViews) {
+        this.useCustomItemViews = useCustomItemViews;
+    }
+
     public void applyOptions() {
         bottomTabs.perform(bottomTabs -> {
             for (int i = 0; i < tabs.size(); i++) {
                 BottomTabOptions tab = tabs.get(i).resolveCurrentOptions(defaultOptions).bottomTabOptions;
+                if (useCustomItemViews && tab.component.hasValue()) {
+                    if (tab.testId.hasValue()) bottomTabs.setTag(i, tab.testId.get());
+                    if (tab.badge.hasValue()) {
+                        CustomBottomTabItemView v = bottomTabs.getCustomItemView(i);
+                        if (v != null) v.setBadge(tab.badge.get(""));
+                    }
+                    continue;
+                }
                 bottomTabs.setIconWidth(i, tab.iconWidth.get(null));
                 bottomTabs.setIconHeight(i, tab.iconHeight.get(null));
                 bottomTabs.setTitleTypeface(i, tab.font.getTypeface(typefaceLoader, defaultTypeface));
@@ -86,6 +106,14 @@ public class BottomTabPresenter {
             int index = bottomTabFinder.findByControllerId(child.getId());
             if (index >= 0) {
                 BottomTabOptions tab = options.bottomTabOptions;
+                if (useCustomItemViews && bottomTabs.getCustomItemView(index) != null) {
+                    if (tab.badge.hasValue()) {
+                        CustomBottomTabItemView v = bottomTabs.getCustomItemView(index);
+                        if (v != null) v.setBadge(tab.badge.get(""));
+                    }
+                    if (tab.testId.hasValue()) bottomTabs.setTag(index, tab.testId.get());
+                    return;
+                }
                 if (tab.iconWidth.hasValue()) bottomTabs.setIconWidth(index, tab.iconWidth.get(null));
                 if (tab.iconHeight.hasValue()) bottomTabs.setIconHeight(index, tab.iconHeight.get(null));
                 if (tab.font.hasValue()) bottomTabs.setTitleTypeface(index, tab.font.getTypeface(typefaceLoader, defaultTypeface));

package/android/src/main/java/com/reactnativenavigation/viewcontrollers/bottomtabs/BottomTabsController.java

@@ -16,6 +16,8 @@ import androidx.coordinatorlayout.widget.CoordinatorLayout;
 import androidx.core.view.ViewCompat;
 import androidx.core.view.WindowInsetsCompat;
 
+import android.util.Log;
+
 import com.aurelhubert.ahbottomnavigation.AHBottomNavigation;
 import com.aurelhubert.ahbottomnavigation.AHBottomNavigationItem;
 import com.reactnativenavigation.options.BottomTabOptions;
@@ -35,7 +37,9 @@ import com.reactnativenavigation.viewcontrollers.viewcontroller.ViewController;
 import com.reactnativenavigation.views.bottomtabs.BottomTabs;
 import com.reactnativenavigation.views.bottomtabs.BottomTabsContainer;
 import com.reactnativenavigation.views.bottomtabs.BottomTabsLayout;
+import com.reactnativenavigation.views.bottomtabs.CustomBottomTabItemView;
 
+import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Deque;
 import java.util.LinkedList;
@@ -43,6 +47,8 @@ import java.util.List;
 
 public class BottomTabsController extends ParentController<BottomTabsLayout> implements AHBottomNavigation.OnTabSelectedListener, TabSelector {
 
+    private static final String LOG_TAG = "BottomTabsController";
+
     private BottomTabsContainer bottomTabsContainer;
     private BottomTabs bottomTabs;
     private final Deque<Integer> selectionStack;
@@ -52,6 +58,7 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
     private final BottomTabsAttacher tabsAttacher;
     private final BottomTabsPresenter presenter;
     private final BottomTabPresenter tabPresenter;
+    private boolean useCustomItemViews;
 
     public BottomTabsAnimator getAnimator() {
         return presenter.getAnimator();
@@ -106,13 +113,59 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
         bottomTabs.setOnTabSelectedListener(this);
         root.addBottomTabsContainer(bottomTabsContainer);
 
+        useCustomItemViews = resolveUseCustomItemViews();
+        tabPresenter.setUseCustomItemViews(useCustomItemViews);
+
         bottomTabs.addItems(createTabs());
+
+        if (useCustomItemViews) {
+            attachCustomItemViewsToCells();
+        }
+
         setInitialTab(resolveCurrentOptions);
         tabsAttacher.attach();
 
         return root;
     }
 
+    private boolean resolveUseCustomItemViews() {
+        if (tabs.isEmpty()) return false;
+        int withComponent = 0;
+        for (ViewController<?> tab : tabs) {
+            BottomTabOptions options = tab.resolveCurrentOptions(initialOptions).bottomTabOptions;
+            if (options.component.hasValue()) withComponent++;
+        }
+        if (withComponent == 0) return false;
+        if (withComponent != tabs.size()) {
+            Log.w(LOG_TAG,
+                    "Mixed bottomTab.component usage detected (" + withComponent + " of "
+                            + tabs.size() + " tabs). All tabs must declare a component or none — "
+                            + "falling back to native rendering for all tabs.");
+            return false;
+        }
+        return true;
+    }
+
+    private void attachCustomItemViewsToCells() {
+        List<CustomBottomTabItemView> overlays = new ArrayList<>();
+        int initialIndex = bottomTabs.getCurrentItem();
+        for (int i = 0; i < tabs.size(); i++) {
+            BottomTabOptions options = tabs.get(i).resolveCurrentOptions(initialOptions).bottomTabOptions;
+            String componentId = options.component.componentId.get(tabs.get(i).getId() + "_tab_" + i);
+            String componentName = options.component.name.get();
+            String badge = options.badge.hasValue() ? options.badge.get() : null;
+            CustomBottomTabItemView itemView = new CustomBottomTabItemView(
+                    getActivity(),
+                    componentId,
+                    componentName,
+                    i,
+                    i == initialIndex,
+                    badge);
+            overlays.add(itemView);
+        }
+        bottomTabs.setCustomItemViews(overlays);
+    }
+
     private void setInitialTab(Options resolveCurrentOptions) {
         int initialTabIndex = 0;
         if (resolveCurrentOptions.bottomTabsOptions.currentTabId.hasValue())
@@ -121,6 +174,9 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
             initialTabIndex = resolveCurrentOptions.bottomTabsOptions.currentTabIndex.get();
         }
         bottomTabs.setCurrentItem(initialTabIndex, false);
+        if (useCustomItemViews) {
+            bottomTabs.onCustomItemViewSelectionChanged(initialTabIndex);
+        }
     }
 
     @NonNull
@@ -294,6 +350,9 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
         ViewController<?> previouslyVisible = getCurrentChild();
         bottomTabs.setCurrentItem(newIndex, false);
         getCurrentChild().onSelected(previouslyVisible);
+        if (useCustomItemViews) {
+            bottomTabs.onCustomItemViewSelectionChanged(newIndex);
+        }
     }
 
     private void saveTabSelection(int newIndex, boolean enableSelectionHistory) {

package/android/src/main/java/com/reactnativenavigation/views/bottomtabs/BottomTabs.java

@@ -8,6 +8,8 @@ import android.content.Context;
 import android.graphics.Color;
 import android.graphics.drawable.Drawable;
 import android.view.View;
+import android.view.ViewGroup;
+import android.widget.FrameLayout;
 import android.widget.LinearLayout;
 
 import androidx.annotation.IntRange;
@@ -25,6 +27,19 @@ public class BottomTabs extends AHBottomNavigation {
     private boolean itemsCreationEnabled = true;
     private boolean shouldCreateItems = true;
     private List<Runnable> onItemCreationEnabled = new ArrayList<>();
+    private final List<CustomBottomTabItemView> customItemViews = new ArrayList<>();
+    private boolean externalCustomItemViewHost = false;
+
+    /**
+     * When enabled, this view stops re-parenting custom React tab item views
+     * into its native cells on every layout pass — the caller assumes full
+     * ownership of where those item views live in the view tree (used by
+     * the customRow floating-row implementation). Existing behavior is
+     * unchanged when this remains {@code false} (the default).
+     */
+    public void setExternalCustomItemViewHost(boolean enabled) {
+        this.externalCustomItemViewHost = enabled;
+    }
 
     public BottomTabs(Context context) {
         super(context);
@@ -131,6 +146,67 @@ public class BottomTabs extends AHBottomNavigation {
         if (tabsContainer != null) tabsContainer.setLayoutDirection(direction.get());
     }
 
+    /**
+     * Replace the visual content of every tab cell with the provided custom
+     * views. The custom view is attached as a child of the AHBottomNavigation
+     * cell view so taps continue to be handled by the native cell. Pass an
+     * empty list to remove all overlays.
+     */
+    public void setCustomItemViews(List<CustomBottomTabItemView> customViews) {
+        clearCustomItemViews();
+        if (customViews == null || customViews.isEmpty()) return;
+
+        customItemViews.addAll(customViews);
+        attachCustomItemViews();
+    }
+
+    public void onCustomItemViewSelectionChanged(int selectedIndex) {
+        for (int i = 0; i < customItemViews.size(); i++) {
+            customItemViews.get(i).setItemSelected(i == selectedIndex);
+        }
+    }
+
+    public CustomBottomTabItemView getCustomItemView(int index) {
+        if (index < 0 || index >= customItemViews.size()) return null;
+        return customItemViews.get(index);
+    }
+
+    public boolean hasCustomItemViews() {
+        return !customItemViews.isEmpty();
+    }
+
+    private void clearCustomItemViews() {
+        for (CustomBottomTabItemView view : customItemViews) {
+            ViewGroup parent = (ViewGroup) view.getParent();
+            if (parent != null) parent.removeView(view);
+        }
+        customItemViews.clear();
+    }
+
+    private void attachCustomItemViews() {
+        if (externalCustomItemViewHost) return;
+        for (int i = 0; i < customItemViews.size(); i++) {
+            View cell = getViewAtPosition(i);
+            if (!(cell instanceof ViewGroup)) continue;
+            CustomBottomTabItemView itemView = customItemViews.get(i);
+            ViewGroup parent = (ViewGroup) itemView.getParent();
+            if (parent != null && parent != cell) parent.removeView(itemView);
+            if (itemView.getParent() == null) {
+                ((ViewGroup) cell).addView(itemView, new FrameLayout.LayoutParams(
+                        FrameLayout.LayoutParams.MATCH_PARENT,
+                        FrameLayout.LayoutParams.MATCH_PARENT));
+            }
+        }
+    }
+
+    @Override
+    protected void onLayout(boolean changed, int l, int t, int r, int b) {
+        super.onLayout(changed, l, t, r, b);
+        if (changed && !customItemViews.isEmpty()) {
+            attachCustomItemViews();
+        }
+    }
+
     private boolean hasItemsAndIsMeasured(int w, int h, int oldw, int oldh) {
         return w != 0 && h != 0 && (w != oldw || h != oldh) && getItemsCount() > 0;
     }

package/android/src/main/java/com/reactnativenavigation/views/bottomtabs/CustomBottomTabItemView.kt

@@ -0,0 +1,73 @@
+package com.reactnativenavigation.views.bottomtabs
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.os.Bundle
+import android.view.MotionEvent
+import android.widget.FrameLayout
+import com.reactnativenavigation.react.ReactView
+
+/**
+ * Hosts a [ReactView] that renders a user-supplied React component as a
+ * bottom tab item. The view sits on top of the native AHBottomNavigation tab
+ * cell and forwards touches through to the underlying cell so native
+ * selection, ripple and `selectTabOnPress: false` keep working.
+ *
+ * The hosted component receives the following props at creation:
+ * `componentId`, `tabIndex`, `selected`, `badge`. Selection updates are
+ * pushed via [setSelected]; badge updates via [setBadge].
+ */
+@SuppressLint("ViewConstructor")
+class CustomBottomTabItemView(
+    context: Context,
+    val componentId: String,
+    val componentName: String,
+    val tabIndex: Int,
+    initialSelected: Boolean,
+    initialBadge: String?
+) : FrameLayout(context) {
+
+    val reactView: ReactView = ReactView(context, componentId, componentName)
+    private var isCurrentlySelected: Boolean = initialSelected
+    private var badge: String? = initialBadge
+
+    init {
+        addView(reactView)
+        reactView.isClickable = false
+        reactView.isFocusable = false
+        isClickable = false
+        isFocusable = false
+        pushProps()
+    }
+
+    /**
+     * Touches must always reach the underlying AHBottomNavigation cell so
+     * that native selection, ripple, accessibility focus and
+     * `selectTabOnPress: false` keep working. Returning false here makes
+     * this view completely transparent to touch input and prevents any
+     * `Touchable*` rendered inside the React tree from swallowing taps.
+     */
+    override fun dispatchTouchEvent(ev: MotionEvent?): Boolean = false
+
+    fun setItemSelected(selected: Boolean) {
+        if (this.isCurrentlySelected == selected) return
+        this.isCurrentlySelected = selected
+        pushProps()
+    }
+
+    fun setBadge(badge: String?) {
+        if (this.badge == badge) return
+        this.badge = badge
+        pushProps()
+    }
+
+    private fun pushProps() {
+        val bundle = Bundle().apply {
+            putString("componentId", componentId)
+            putInt("tabIndex", tabIndex)
+            putBoolean("selected", isCurrentlySelected)
+            if (badge != null) putString("badge", badge)
+        }
+        reactView.setProps(bundle)
+    }
+}