https://github.com/bamlab/react-native-screen-sizer
A react native library to simulate different screen sizes on the same device
https://github.com/bamlab/react-native-screen-sizer
developer-tools react-native
Last synced: about 1 year ago
JSON representation
A react native library to simulate different screen sizes on the same device
- Host: GitHub
- URL: https://github.com/bamlab/react-native-screen-sizer
- Owner: bamlab
- License: mit
- Created: 2023-06-19T09:54:56.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-02-27T09:01:03.000Z (over 2 years ago)
- Last Synced: 2024-04-18T16:40:32.170Z (about 2 years ago)
- Topics: developer-tools, react-native
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@bam.tech/react-native-screen-sizer
- Size: 2.51 MB
- Stars: 16
- Watchers: 7
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ReactNative Screen Sizer
Quickly check how your app looks on different screen sizes.
## Setup
```sh
yarn add @bam.tech/react-native-screen-sizer
```
You'll also need to have these dependencies installed:
- if you use `expo go`:
```bash
npx expo install react-native-safe-area-context
```
- if you use `expo` with a custom build:
```bash
npx expo install react-native-safe-area-context expo-dev-client
```
- if you use a bare React Native project:
```bash
yarn add react-native-safe-area-context
npx pod-install
```
Then, add it to `App.tsx`:
```tsx
import { SafeAreaProvider } from 'react-native-safe-area-context';
/* 👋 Add the import */
import * as ScreenSizer from '@bam.tech/react-native-screen-sizer';
/* 👋 Call this at the top-level of App.tsx. It will handle some things like
register shortcuts in the dev menu. */
ScreenSizer.setup();
export const App = () => {
// ...
return (
{/* 👋 `ScreenSizer.Wrapper` must be inserted inside `SafeAreaProvider`
but around any provider or component that uses safe area dimensions */}
{/* The rest of your providers and your app */}
);
};
```
> **NOTE**: The `Wrapper` and the setup function are no-ops in release builds,
> so you can safely add them without adding `__DEV__` conditions yourself.
## Usage
By default, the screen sizer is disabled when you run your app. You can enable it by different ways:
- Open the dev menu (⌘ cmd + D on iOS or
⌘ cmd + M on Android)
and tap `"📐 Toggle Screen Sizer"`
- or import the function `ScreenSizer.toggleScreenSizer()` in your code
and link it to a button to activate the screen sizer
Compatibility of each method by project type:
| | React Native Dev Menu | Expo Dev Menu | `toggle` function |
| ---------------------- | :-------------------: | :-----------: | :---------------: |
| Bare React Native | ✅ | ❌ | ✅ |
| Expo Go | ❌ | ❌ | ✅ |
| Expo Custom Dev Client | ✅ | ✅ | ✅ |
## Making it work well
Things should be mostly ok without changing anything in your app code, but you can get better fidelity (and by the way handle screen resizing on device like iPad better) by following these guidelines:
### Use a big screen as the "base device"
We recommend using a big screen (eg `iPhone 14 Pro Max`) as the "base device" to develop on.
If your base device is too small for one of the screens you want to emulate, the behavior for this screen is undefined and you'll get a warning in the console.
### Read screen/window/safe-area dimensions through `react-native-safe-area-context`
- ❌ `import { SafeAreaView, useWindowDimensions } from "react-native"`
- ✅ `import { SafeAreaView, useSafeAreaInsets, useSafeAreaFrame } from "react-native-safe-area-context"`
`react-native-screen-sizer` adds a custom `react-native-safe-area-context` provider to emulate the safe area insets and frame of the "sized device".
Currently, other ways to read these dimensions (like the ones in the base `react-native` package) are not supported.
### Always read screen/window/safe-area dimensions in a reactive manner
- ❌ `import { Dimensions } from "react-native`
- ❌ `import { initialMetrics } from "react-native-safe-area-context"`
- ✅ `import { SafeAreaView, useSafeAreaInsets, useSafeAreaFrame } from "react-native-safe-area-context"`
If you use "static" dimensions, you app won't re-render properly when the device size changes. This applies to the "emulated size" from this package, but also to the real size (eg window resizing on iPad or M1 macs, or switching to landscape mode), so it's a good thing to do anyway!
### Eslint config
You can setup these eslint rules to enforce some of the guidelines above:
```json
{
"no-restricted-imports": [
"error",
{
"paths": [
{
"name": "react-native",
"importNames": ["Dimensions", "useWindowDimensions"],
"message": "Read dimensions with `useSafeAreaFrame` from `react-native-safe-area-context` instead (to support screen-sizer)"
}
]
}
]
}
```
## API
### `ScreenSizer.setup`
A function that should be called on initialization.
### `ScreenSizer.Wrapper`
A wrapper component to simulate the different screens.
| Props | Type | Description |
| ------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| devices | `Array`, optional | A list of device specifications. If a device is bigger than the host device, a warning will be prompted in the console. Default to `ScreenSizer.defaultDevices.all`. |
| activatedByDefault | boolean, optional | Specify if the ScreenSizer should be activated by default when the app starts. Default to false. |
> **NOTE**: `Device` has the following type:
>
> ```typescript
> export type Device = {
> name: string;
> width: number;
> height: number;
> insets?: Partial;
> landscapeInsets?: Partial;
> };
>
> type Insets = {
> top: number;
> bottom: number;
> left: number;
> right: number;
> };
> ```
### `ScreenSizer.defaultDevices`
An object containing different default device specifications, meant to be used for the `devices` props of the wrapper.
| Properties | Type | Description: width x height (topInset - bottomInset) |
| ------------ | --------------- | ---------------------------------------------------- |
| iPhoneSE2016 | `Device` | 320 x 568 (20 - 0) |
| iPhoneSE2022 | `Device` | 375 x 667 (20 - 0) |
| iPhone12Mini | `Device` | 375 x 812 (44 - 34) |
| iPhone12Pro | `Device` | 390 x 844 (47 - 34) |
| galaxyS8 | `Device` | 360 x 740 (24 - 0) |
| all | `Array` | List of all previous devices. |
### `ScreenSizer.toggleScreenSizer`
A function to activate or deactivate the screen-sizer mode. No parameters.
## Current limitations
- On android, the **status bar** inset is applied as if the status bar is visible and translucent
## 👉 About Bam
We are a 100 people company developing and designing multi-platform applications with [React Native](https://www.bam.tech/expertise/react-native) using the Lean & Agile methodology. To get more information on the solutions that would suit your needs, feel free to get in touch by [email](mailto:contact@bam.tech) or through our [contact form](https://www.bam.tech/en/contact)!
We will always answer you with pleasure 😁