feat(Android, Tabs): safe area component for Android

[kligarski]

Description

Adds implementation for handling safe area on Android for bottom tabs.

Implementation has been adapted from react-native-safe-area-context.

TODO:

• change native layout so that TabScreen renders under the tab bar (to allow using transparent tab bar)
• check implementation for older Android APIs (I checked APIs: 25, 28, 29, 30, 36 and 24 on Paper)
• add simple API (for all edges) to control which types of insets are used by SafeAreaView component (system and/or interface bars)
• [Separate PR] add per-edge API to control which types of insets are used by SafeAreaView component (system and/or interface bars) (https://github.com/software-mansion/react-native-screens-labs/issues/434)
• [Separate PR] fix interaction with Stack v4 (CustomToolbar) (https://github.com/software-mansion/react-native-screens-labs/issues/435)
• [Separate PR] There were no problems with using margins for now so I left it as it was. We can change this later to padding or add a prop to switch between padding and margins on both Android and iOS. (https://github.com/software-mansion/react-native-screens-labs/issues/436)

Screen.Recording.2025-09-15.at.15.11.21.mov

Transparent tab bar

top: false, bottom: false	top: true, bottom: false	top: true, bottom: true

Changes to TabsHost's layout

SafeAreaView

After internal discussion about approach to SafeAreaView, we had following conclusions:

• as edge-to-edge becomes desirable (and is the default for apps targeting Android SDK 35 or above), and to simplify layout handling, we want the Screens of our navigation containers (e.g. StackScreen, BottomTabsScreen) to have full dimensions of their parents, even if it means that they will be laid out behind navigation bars (header in Stack, tab bar),
• SafeAreaView will provide unified way to handle the safe area,
• on Android, we want to control which insets we want to handle:
  • system insets (received from onApplyWindowInsets), e.g. systemBars, displayCutout
  • interface insets - custom insets from navigation bars, e.g. bottomNavigationView

Before this PR

Prior to this PR, we were using LinearLayout for TabsHost:

class TabsHost(
    val reactContext: ThemedReactContext,
) : LinearLayout(reactContext),
    TabScreenDelegate {
    // ...
    private val bottomNavigationView: BottomNavigationView =
        BottomNavigationView(wrappedContext).apply {
            layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.WRAP_CONTENT)
        }

    private val contentView: FrameLayout =
        FrameLayout(reactContext).apply {
            layoutParams =
                LinearLayout
                    .LayoutParams(
                        LayoutParams.MATCH_PARENT,
                        LayoutParams.WRAP_CONTENT,
                    ).apply {
                        weight = 1f
                    }
            id = ViewIdGenerator.generateViewId()
        }
    // ...
}

This approach had following problems:

• contentView did not have dimensions of its parent, which is not what we wanted,
• Yoga wasn't aware of contentView's height - all content inside TabScreen was laid out as if the screen had full height of its parent -> this meant that contentView's dimensions and actual content dimensions were not in sync,
• it did not support using translucent tab bar - screen's content was cut off outside of contentView's bounds.

Approach in this PR

In this PR, we change TabsHost's layout to FrameLayout which allows multiple views placed on top of each other - this is what we want to achieve (tab bar floating over content, attached to the bottom).

To attach bottomNavigationView to the bottom, we use Gravity.BOTTOM.

class TabsHost(
    val reactContext: ThemedReactContext,
) : FrameLayout(reactContext),
    TabScreenDelegate,
    SafeAreaProvider,
    View.OnLayoutChangeListener {
    // ...
    private val bottomNavigationView: BottomNavigationView =
        BottomNavigationView(wrappedContext).apply {
            layoutParams =
                LayoutParams(
                    LayoutParams.MATCH_PARENT,
                    LayoutParams.WRAP_CONTENT,
                    Gravity.BOTTOM,
                )
        }

    private val contentView: FrameLayout =
        FrameLayout(reactContext).apply {
            layoutParams =
                LayoutParams(
                    LayoutParams.MATCH_PARENT,
                    LayoutParams.MATCH_PARENT,
                )
            id = ViewIdGenerator.generateViewId()
        }
    // ...
}

Now, we can:

1. use opaque or translucent bottomNavigationView,
2. use SafeAreaView to control how much space can the actual content take (do we allow it to render under bottomNavigationView).

Support for older Android versions

On Android versions prior to R, insets dispatch is broken (children of ViewGroup receive insets from previous child; they should all receive the same insets). That's why we need to override dispatchApplyWindowInsets implementation in TabsHost. In ViewGroup's implementation of this method, View's implementation is used (via super) - we can't access this directly. Unfortunately, View's implementation sets some private flags which are used by default onApplyWindowInsets implementation. If we try to use onApplyWindowInsets on API 28 without setting the private flag, application goes into infinite loop (fitSystemWindows calls dispatchApplyWindowInsets -> we might want to investigate this in more detail). As we don't use insets in TabsHost, I decided not to call onApplyWindowInsets in TabsHost at all. I haven't found any problems with it yet.

Changes

• add implementation for SafeAreaView and related classes for both architectures
• add SafeAreaProvider interface and implement it for TabsHost
• change TabsHost to use FrameLayout:
  • make TabsScreen layout behind tab bar (take full available height to match JS screen)
• override dispatchApplyWindowInsets in TabsHost in order to fix insets for older Android versions
• add insetType prop to control what kind of insets should SafeAreaView respect (all, only system, only interface)

Test code and steps to reproduce

Run TestBottomTabs with uncommented SafeAreaView. You can change which edges are enabled and add insetType prop.

Checklist

• Included code example that can be used to test this change
• Updated TS types
• Updated documentation:
  • https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
  • https://github.com/software-mansion/react-native-screens/blob/main/native-stack/README.md
  • https://github.com/software-mansion/react-native-screens/blob/main/src/types.tsx
  • https://github.com/software-mansion/react-native-screens/blob/main/src/native-stack/types.tsx
• Ensured that CI passes

[t0maboro]

I had some issues with testing runtime locally, but verified with @kligarski that it's working well.

[kligarski]

Currently, SafeAreaView on Android is implemented only for bottom tabs. We're planning to add a flag to enable SafeAreaView globally in our components very soon so I'm not sure if I should create any test screen for this PR? (It would be very similar to current TestBottomTabs).

Let me know what you think.

[kkafar]

Okay. The PR looks really nice. I have few requests, please answer them.

[kkafar]

Why are we using insets listener here, instead of regular onApplyWindowInsets method?

[kligarski]

I used it to get WindowInsetsCompat instance instead of getting WindowInsets and converting it manually.

[kkafar]

hate this. Let's keep our fingers crossed we won't run into problems with this.

[kkafar]

We're modifying here non-volatile value possible across thread boundaries 🙈

I won't demand changes here, since this code is already a bit battle tested, but man...

[kkafar]

The PR looks really good now. I have singl remark. Please answer it. I'll check the runtime behaviour in meantime.

[kkafar]

Realised it is not used yet. The app builds fine. I think we can proceed after cleaning up what I've indicated in preceding review.