{"id":29023069,"url":"https://github.com/bamlab/react-native-screen-sizer","last_synced_at":"2025-06-26T03:05:15.232Z","repository":{"id":176364917,"uuid":"655641883","full_name":"bamlab/react-native-screen-sizer","owner":"bamlab","description":"A react native library to simulate different screen sizes on the same device","archived":false,"fork":false,"pushed_at":"2024-02-27T09:01:03.000Z","size":2627,"stargazers_count":16,"open_issues_count":2,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-04-18T16:40:32.170Z","etag":null,"topics":["developer-tools","react-native"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@bam.tech/react-native-screen-sizer","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bamlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-06-19T09:54:56.000Z","updated_at":"2024-04-11T14:44:46.000Z","dependencies_parsed_at":"2023-11-20T10:49:07.783Z","dependency_job_id":null,"html_url":"https://github.com/bamlab/react-native-screen-sizer","commit_stats":null,"previous_names":["bamlab/react-native-screen-sizer"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/bamlab/react-native-screen-sizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamlab%2Freact-native-screen-sizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamlab%2Freact-native-screen-sizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamlab%2Freact-native-screen-sizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamlab%2Freact-native-screen-sizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bamlab","download_url":"https://codeload.github.com/bamlab/react-native-screen-sizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bamlab%2Freact-native-screen-sizer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261990350,"owners_count":23241188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","react-native"],"created_at":"2025-06-26T03:05:14.712Z","updated_at":"2025-06-26T03:05:15.216Z","avatar_url":"https://github.com/bamlab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"./assets/screen-sizer-logo.png\" alt=\"Screen Sizer logo\" width=\"400px\" /\u003e\n\u003c/p\u003e\n\n# ReactNative Screen Sizer\n\nQuickly check how your app looks on different screen sizes.\n\n\u003cimg src=\"./assets/demo.gif\" alt=\"Live demo of the usage of the library\" width=\"300\" /\u003e\n\n## Setup\n\n```sh\nyarn add @bam.tech/react-native-screen-sizer\n```\n\nYou'll also need to have these dependencies installed:\n\n- if you use `expo go`:\n  ```bash\n  npx expo install react-native-safe-area-context\n  ```\n- if you use `expo` with a custom build:\n  ```bash\n  npx expo install react-native-safe-area-context expo-dev-client\n  ```\n- if you use a bare React Native project:\n  ```bash\n  yarn add react-native-safe-area-context\n  npx pod-install\n  ```\n\nThen, add it to `App.tsx`:\n\n```tsx\nimport { SafeAreaProvider } from 'react-native-safe-area-context';\n\n/* 👋 Add the import */\nimport * as ScreenSizer from '@bam.tech/react-native-screen-sizer';\n\n/* 👋 Call this at the top-level of App.tsx. It will handle some things like \nregister shortcuts in the dev menu. */\nScreenSizer.setup();\n\nexport const App = () =\u003e {\n  // ...\n\n  return (\n    \u003cSafeAreaProvider\u003e\n      \u003cScreenSizer.Wrapper\n        /* 👋 The list of devices that will be emulated. You can use some of our\n        default devices, custom ones, or the keyword 'hostDevice' to reference\n        your current host device. */\n        devices={[...ScreenSizer.defaultDevices.all, 'hostDevice']}\n      \u003e\n        {/* 👋 `ScreenSizer.Wrapper` must be inserted inside `SafeAreaProvider`\n        but around any provider or component that uses safe area dimensions */}\n        {/* The rest of your providers and your app */}\n      \u003c/ScreenSizer.Wrapper\u003e\n    \u003c/SafeAreaProvider\u003e\n  );\n};\n```\n\n\u003e **NOTE**: The `Wrapper` and the setup function are no-ops in release builds,\n\u003e so you can safely add them without adding `__DEV__` conditions yourself.\n\n## Usage\n\nBy default, the screen sizer is disabled when you run your app. You can enable it by different ways:\n\n- Open the dev menu (\u003ckbd\u003e⌘ cmd\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e on iOS or\n  \u003ckbd\u003e⌘ cmd\u003c/kbd\u003e + \u003ckbd\u003eM\u003c/kbd\u003e on Android)\n  and tap `\"📐 Toggle Screen Sizer\"`\n- or import the function `ScreenSizer.toggleScreenSizer()` in your code\n  and link it to a button to activate the screen sizer\n\nCompatibility of each method by project type:\n\n|                        | React Native Dev Menu | Expo Dev Menu | `toggle` function |\n| ---------------------- | :-------------------: | :-----------: | :---------------: |\n| Bare React Native      |          ✅           |      ❌       |        ✅         |\n| Expo Go                |          ❌           |      ❌       |        ✅         |\n| Expo Custom Dev Client |          ✅           |      ✅       |        ✅         |\n\n## Making it work well\n\nThings 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:\n\n### Use a big screen as the \"base device\"\n\nWe recommend using a big screen (eg `iPhone 14 Pro Max`) as the \"base device\" to develop on.\n\nIf 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.\n\n### Read screen/window/safe-area dimensions through `react-native-safe-area-context`\n\n- ❌ `import { SafeAreaView, useWindowDimensions } from \"react-native\"`\n- ✅ `import { SafeAreaView, useSafeAreaInsets, useSafeAreaFrame } from \"react-native-safe-area-context\"`\n\n`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\".\nCurrently, other ways to read these dimensions (like the ones in the base `react-native` package) are not supported.\n\n### Always read screen/window/safe-area dimensions in a reactive manner\n\n- ❌ `import { Dimensions } from \"react-native`\n- ❌ `import { initialMetrics } from \"react-native-safe-area-context\"`\n- ✅ `import { SafeAreaView, useSafeAreaInsets, useSafeAreaFrame } from \"react-native-safe-area-context\"`\n\nIf 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!\n\n### Eslint config\n\nYou can setup these eslint rules to enforce some of the guidelines above:\n\n```json\n{\n  \"no-restricted-imports\": [\n    \"error\",\n    {\n      \"paths\": [\n        {\n          \"name\": \"react-native\",\n          \"importNames\": [\"Dimensions\", \"useWindowDimensions\"],\n          \"message\": \"Read dimensions with `useSafeAreaFrame` from `react-native-safe-area-context` instead (to support screen-sizer)\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n## API\n\n### `ScreenSizer.setup`\n\nA function that should be called on initialization.\n\n### `ScreenSizer.Wrapper`\n\nA wrapper component to simulate the different screens.\n\n| Props              | Type                                      | Description                                                                                                                                                          |\n| ------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| devices            | `Array\u003cDevice \\| 'hostDevice'\u003e`, 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`. |\n| activatedByDefault | boolean, optional                         | Specify if the ScreenSizer should be activated by default when the app starts. Default to false.                                                                     |\n\n\u003e **NOTE**: `Device` has the following type:\n\u003e\n\u003e ```typescript\n\u003e export type Device = {\n\u003e   name: string;\n\u003e   width: number;\n\u003e   height: number;\n\u003e   insets?: Partial\u003cInsets\u003e;\n\u003e   landscapeInsets?: Partial\u003cInsets\u003e;\n\u003e };\n\u003e\n\u003e type Insets = {\n\u003e   top: number;\n\u003e   bottom: number;\n\u003e   left: number;\n\u003e   right: number;\n\u003e };\n\u003e ```\n\n### `ScreenSizer.defaultDevices`\n\nAn object containing different default device specifications, meant to be used for the `devices` props of the wrapper.\n\n| Properties   | Type            | Description: width x height (topInset - bottomInset) |\n| ------------ | --------------- | ---------------------------------------------------- |\n| iPhoneSE2016 | `Device`        | 320 x 568 (20 - 0)                                   |\n| iPhoneSE2022 | `Device`        | 375 x 667 (20 - 0)                                   |\n| iPhone12Mini | `Device`        | 375 x 812 (44 - 34)                                  |\n| iPhone12Pro  | `Device`        | 390 x 844 (47 - 34)                                  |\n| galaxyS8     | `Device`        | 360 x 740 (24 - 0)                                   |\n| all          | `Array\u003cDevice\u003e` | List of all previous devices.                        |\n\n### `ScreenSizer.toggleScreenSizer`\n\nA function to activate or deactivate the screen-sizer mode. No parameters.\n\n## Current limitations\n\n- On android, the **status bar** inset is applied as if the status bar is visible and translucent\n\n## 👉 About Bam\n\nWe are a 100 people company developing and designing multi-platform applications with [React Native](https://www.bam.tech/expertise/react-native) using the Lean \u0026 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)!\n\nWe will always answer you with pleasure 😁\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbamlab%2Freact-native-screen-sizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbamlab%2Freact-native-screen-sizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbamlab%2Freact-native-screen-sizer/lists"}