Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/zoontek/react-native-edge-to-edge

Effortlessly enable edge-to-edge display in React Native (formerly known as react-native-bars).
https://github.com/zoontek/react-native-edge-to-edge

edge-to-edge navigation-bar react-native status-bar

Last synced: 1 day ago
JSON representation

Effortlessly enable edge-to-edge display in React Native (formerly known as react-native-bars).

Host: GitHub
URL: https://github.com/zoontek/react-native-edge-to-edge
Owner: zoontek
License: mit
Created: 2021-11-13T00:36:28.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2025-01-27T13:22:13.000Z (18 days ago)
Last Synced: 2025-02-03T08:05:21.953Z (11 days ago)
Topics: edge-to-edge, navigation-bar, react-native, status-bar
Language: TypeScript
Homepage:
Size: 4.59 MB
Stars: 730
Watchers: 5
Forks: 24
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS

Awesome Lists containing this project

README

        # react-native-edge-to-edge

Effortlessly enable [edge-to-edge](https://developer.android.com/develop/ui/views/layout/edge-to-edge) display in React Native, allowing your Android (v6 and above) app content to flow seamlessly beneath the system bars.

[![mit licence](https://img.shields.io/dub/l/vibe-d.svg?style=for-the-badge)](https://github.com/zoontek/react-native-edge-to-edge/blob/main/LICENSE)

[![npm version](https://img.shields.io/npm/v/react-native-edge-to-edge?style=for-the-badge)](https://www.npmjs.org/package/react-native-edge-to-edge)

[![npm downloads](https://img.shields.io/npm/dt/react-native-edge-to-edge.svg?label=downloads&style=for-the-badge)](https://www.npmjs.org/package/react-native-edge-to-edge)



## Credits

This project has been built and is maintained thanks to the support from [Expo](https://expo.dev).



  



## Support

This library follows the React Native [releases support policy](https://github.com/reactwg/react-native-releases/blob/main/docs/support.md).


It is supporting the **latest version**, and the **two previous minor series**.

## Motivations

### Android 15

Recently, Google introduced a significant change: apps targeting SDK 35 will have edge-to-edge display [enforced by default](https://developer.android.com/about/versions/15/behavior-changes-15#edge-to-edge) on Android 15+. Google is _likely_ to mandate that app updates on the Play Store target SDK 35 starting on August 31, 2025. This assumption is based on the [previous years' requirements following a similar timeline](https://support.google.com/googleplay/android-developer/answer/11926878?sjid=11853000253346477363-EU#zippy=%2Care-there-any-exceptions-for-existing-apps-targeting-api-or-below:~:text=App%20update%20requirements).

### Consistency

iOS has long used edge-to-edge displays, so adopting this design across all platforms ensures a consistent user experience. It also simplifies managing safe areas, eliminating the need for special cases specific to Android.

### Immersive mode

[Immersive mode](https://developer.android.com/develop/ui/views/layout/immersive) allows you to hide the status and navigation bars, making it ideal for full-screen experiences. Currently, the built-in [`StatusBar`](https://reactnative.dev/docs/statusbar) component uses [`FLAG_FULLSCREEN`](https://developer.android.com/reference/android/view/WindowManager.LayoutParams#FLAG_FULLSCREEN), a flag that has been deprecated since Android 11.

## Installation

```bash

$ npm i -S react-native-edge-to-edge

# --- or ---

$ yarn add react-native-edge-to-edge

```

### Pick a parent theme

This library requires you to update the parent of your Android `AppTheme` to an edge-to-edge version. Don't worry, it's very easy to understand! You just need to choose a theme based on the current value:

| If you currently have…                               | …you should use                            |

| :--------------------------------------------------- | :----------------------------------------- |

| `Theme.AppCompat.DayNight.NoActionBar`               | `Theme.EdgeToEdge`                         |

| `Theme.MaterialComponents.DayNight.NoActionBar`      | `Theme.EdgeToEdge.Material2`               |

| `Theme.Material3.DayNight.NoActionBar`               | `Theme.EdgeToEdge.Material3`               |

| `Theme.Material3.DynamicColors.DayNight.NoActionBar` | `Theme.EdgeToEdge.Material3.Dynamic`       |

| `Theme.AppCompat.Light.NoActionBar`                  | `Theme.EdgeToEdge.Light`                   |

| `Theme.MaterialComponents.Light.NoActionBar`         | `Theme.EdgeToEdge.Material2.Light`         |

| `Theme.Material3.Light.NoActionBar`                  | `Theme.EdgeToEdge.Material3.Light`         |

| `Theme.Material3.DynamicColors.Light.NoActionBar`    | `Theme.EdgeToEdge.Material3.Dynamic.Light` |

### Expo

Add the library plugin in your `app.json` config file and [create a new build](https://docs.expo.dev/develop/development-builds/create-a-build) 👷:

```json

{

  "expo": {

    "plugins": [

      [

        "react-native-edge-to-edge",

        {

          "android": {

            "parentTheme": "Light",

            "enforceNavigationBarContrast": false

          }

        }

      ]

    ]

  }

}

```

_📌 The available plugins options are:_

```ts

type ParentTheme =

  | "Default" // uses `Theme.EdgeToEdge`

  | "Material2" // uses `Theme.EdgeToEdge.Material2`

  | "Material3" // uses `Theme.EdgeToEdge.Material3`

  | "Material3.Dynamic" // uses `Theme.EdgeToEdge.Material3.Dynamic`

  | "Light" // uses `Theme.EdgeToEdge.Light`

  | "Material2.Light" // uses `Theme.EdgeToEdge.Material2.Light`

  | "Material3.Light" // uses `Theme.EdgeToEdge.Material3.Light`

  | "Material3.Dynamic.Light"; // uses `Theme.EdgeToEdge.Material3.Dynamic.Light`

type Options = {

  android?: {

    // see the "Pick a parent theme" section

    parentTheme?: ParentTheme; // optional (default: `Default`)

    // see the "Transparent navigation bar" section

    enforceNavigationBarContrast?: boolean; // optional (default: `true`)

  };

};

```

> [!NOTE]

> This library is not yet supported in the [Expo Go](https://expo.dev/go) sandbox app.

### Bare React Native

Edit your `android/app/src/main/res/values/styles.xml` file to inherit from one of the provided themes:

```xml

  

  

    <!-- … -->

    <!-- disable the contrasting background of the navigation bar (optional) -->

    <item name="enforceNavigationBarContrast">false</item>

  

```

## Considerations

### Transparent navigation bar

By default, this library adopts [Android 15 defaults](https://developer.android.com/about/versions/15/behavior-changes-15#ux): a fully transparent status bar, a fully transparent gesture navigation bar, and a semi-opaque button navigation bar. To enforce full transparency in all cases, set the `enforceNavigationBarContrast` option to `false`.


Note that by doing so, you will need to manage the navigation bar style (using `SystemBars`) in the same way you handle the status bar.

### Keyboard management

Enabling edge-to-edge display disrupts Android keyboard management (`android:windowSoftInputMode="adjustResize"`), requiring an alternative solution. While [`KeyboardAvoidingView`](https://reactnative.dev/docs/keyboardavoidingview) is a viable option, we recommend using [react-native-keyboard-controller](https://github.com/kirillzyusko/react-native-keyboard-controller) for its enhanced capabilities.

### Safe area management

Effective safe area management is essential to prevent content from being displayed behind transparent system bars. To achieve this, we highly recommend using [`react-native-safe-area-context`](https://github.com/th3rdwave/react-native-safe-area-context), a well-known and trusted library.

### Modal component quirks

React native built-in [`Modal`](https://reactnative.dev/docs/modal) component runs in its own native context, so be sure to set both the `statusBarTranslucent` and `navigationBarTranslucent` props to `true`. However, we recommend using the [react-navigation modals](https://reactnavigation.org/docs/modal) or the [`expo-router` modal screens](https://docs.expo.dev/router/advanced/modals/#modal-screen-using-expo-router) instead.

## API

### SystemBars

Using [`StatusBar`](https://reactnative.dev/docs/statusbar), [`expo-status-bar`](https://docs.expo.dev/versions/latest/sdk/status-bar), or [`expo-navigation-bar`](https://docs.expo.dev/versions/latest/sdk/navigation-bar/) in apps with edge-to-edge layout enabled may cause unexpected behavior, as they currently use [deprecated APIs](https://developer.android.com/about/versions/15/behavior-changes-15#deprecated-apis).


To address this, we provide a component to replace them and manage your app's system bars: ``.

```tsx

import { SystemBars } from "react-native-edge-to-edge";

// "auto" is based on current color scheme (light -> dark content, dark -> light content)

type Style = "auto" | "light" | "dark";

type SystemBarsProps = {

  // set the color of the system bar content (as no effect on semi-opaque navigation bar)

  style?: Style | { statusBar?: Style; navigationBar?: Style };

  // hide system bars (the navigation bar cannot be hidden on iOS)

  hidden?: boolean | { statusBar?: boolean; navigationBar?: boolean };

};

const App = () => (

  <>

    

    {/* … */}

  >

);

```

#### SystemBars.pushStackEntry

```ts

const entry: SystemBarsEntry = SystemBars.pushStackEntry(

  props /*: SystemBarsProps */,

);

```

#### SystemBars.popStackEntry

```ts

SystemBars.popStackEntry(entry /*: SystemBarsEntry */);

```

#### SystemBars.replaceStackEntry

```ts

const entry: SystemBarsEntry = SystemBars.replaceStackEntry(

  entry /*: SystemBarsEntry */,

  props /*: SystemBarsProps */,

);

```

## Third-party libraries 🧩

If you're an author and your package interferes with edge-to-edge, refer to the [`react-native-is-edge-to-edge` `README.md`](./react-native-is-edge-to-edge) for compatibility instructions.

## Troubleshooting 🤔

#### The system bars stays opaque

Until third-party libraries officially add support for `react-native-edge-to-edge` to set these options automatically, you may need to adjust them manually to prevent interference with the library.

For example, make sure to set `react-native-reanimated` `useAnimatedKeyboard` `isStatusBarTranslucentAndroid` and `isNavigationBarTranslucentAndroid` to `true` (until [this PR](https://github.com/software-mansion/react-native-reanimated/pull/6732) is merged), or to replace all occurrences of the built-in `StatusBar`, [`expo-status-bar`](https://docs.expo.dev/versions/latest/sdk/status-bar) and [`expo-navigation-bar`](https://docs.expo.dev/versions/latest/sdk/navigation-bar/) with `SystemBars`.

#### The navigation bar style is erratic

There's currently [an open issue](https://issuetracker.google.com/issues/346386744) with the Android 15 emulator image regarding the navigation bar style when it is is fully transparent. This issue does not occur on physical devices.