{"id":11800,"library":"react-native-size-matters","title":"React Native UI Scaling Utility","description":"react-native-size-matters is a lightweight utility library for React Native designed to simplify the scaling of UI elements across various device screen sizes. It helps developers avoid manually adjusting layouts for different screen dimensions by providing a set of robust scaling functions (e.g., `scale`, `verticalScale`, `moderateScale`, `moderateVerticalScale`) and a `ScaledSheet` API that automatically processes style annotations. The library is currently stable at version `0.4.2`, with recent minor updates suggesting an active development and maintenance cadence. Its key differentiators include being lightweight with zero external dependencies beyond `react-native` itself, and offering flexible scaling options, including linear and moderate scaling with adjustable factors. It promotes a \"develop once\" approach, aiming for consistent UI appearance starting from a standard ~5-inch mobile device.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/nirsky/react-native-size-matters","tags":["javascript","react-native","scaling"],"install":[{"cmd":"npm install react-native-size-matters","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-size-matters","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-size-matters","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a React Native specific library and requires React Native as a peer dependency for its functionality.","package":"react-native","optional":false}],"imports":[{"note":"These are named exports for the primary scaling functions. Shorthand aliases like `s`, `vs`, `ms`, `mvs` are also available as named exports.","wrong":"import scale from 'react-native-size-matters';\n// Or for CJS (less common in modern RN):\nconst scale = require('react-native-size-matters').scale;","symbol":"scale, verticalScale, moderateScale","correct":"import { scale, verticalScale, moderateScale } from 'react-native-size-matters';"},{"note":"`ScaledSheet` is a named export that allows defining styles with scaling annotations.","wrong":"import ScaledSheet from 'react-native-size-matters';","symbol":"ScaledSheet","correct":"import { ScaledSheet } from 'react-native-size-matters';"},{"note":"While ES modules (`import`) are standard in modern React Native, CommonJS `require` can still be used to access all exports in some environments.","symbol":"All exports (CommonJS)","correct":"const { scale, verticalScale, ScaledSheet } = require('react-native-size-matters');"}],"quickstart":{"code":"import React from 'react';\nimport { View, Text, StyleSheet } from 'react-native';\nimport { scale, verticalScale, moderateScale, ScaledSheet } from 'react-native-size-matters';\n\nconst App = () => {\n  return (\n    <View style={styles.container}>\n      <Text style={styles.scaledText}>Scaled Text (Width based: 20@s)</Text>\n      <View style={styles.box}>\n        <Text style={styles.boxText}>Box</Text>\n      </View>\n      <Text style={{ fontSize: moderateScale(16, 0.3), marginTop: verticalScale(10) }}>\n        Moderately Scaled Text\n      </Text>\n      <Text style={rawStyles.normalText}>Normal Text (No Scaling)</Text>\n    </View>\n  );\n};\n\nconst rawStyles = StyleSheet.create({\n  normalText: {\n    fontSize: 16,\n    color: '#666',\n    marginTop: 20\n  }\n});\n\nconst styles = ScaledSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    backgroundColor: '#F5FCFF',\n    padding: '20@ms'\n  },\n  scaledText: {\n    fontSize: '20@s',\n    color: '#333',\n    marginBottom: '10@vs'\n  },\n  box: {\n    width: '150@s',\n    height: '100@vs',\n    backgroundColor: 'lightblue',\n    justifyContent: 'center',\n    alignItems: 'center',\n    borderRadius: '8@ms0.3',\n    marginVertical: '20@vs'\n  },\n  boxText: {\n    fontSize: '18@ms',\n    color: 'darkblue'\n  }\n});\n\nexport default App;\n","lang":"typescript","description":"This example demonstrates both functional scaling (`moderateScale`, `verticalScale`) and the `ScaledSheet` API with various annotations (`@s`, `@vs`, `@ms`, `@ms<factor>`) to scale UI elements like text and boxes, adapting them to different screen sizes in React Native. It also shows a regular `StyleSheet` for comparison."},"warnings":[{"fix":"If you are configuring custom guideline sizes, migrate your Babel configuration to use `babel-plugin-dotenv-import` instead of `react-native-dotenv`. Ensure your `.babelrc` or `babel.config.js` is updated accordingly.","message":"Version `0.4.0` introduced a breaking change for configuring \"Changing the Default Guideline Sizes\". The environment library used for this configuration was switched from `react-native-dotenv` to `babel-plugin-dotenv-import`.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Upgrade to `react-native-size-matters@0.4.1` or higher to resolve potential issues with string values in styles. Always ensure that `ScaledSheet` annotations are correctly formatted if you intend to use strings for scaled values.","message":"Prior to `v0.4.1`, there were issues where certain style values provided as strings could lead to errors or unexpected behavior. This was addressed in `v0.4.1`.","severity":"gotcha","affected_versions":"<0.4.1"},{"fix":"Upgrade to `react-native-size-matters@0.1.4` or higher. When using TypeScript, ensure that style properties expecting numbers are provided with numerical values, or that string values are correctly annotated for `ScaledSheet` to process them.","message":"In versions prior to `0.1.4`, some styles caused TypeScript errors when provided with string values, particularly if not correctly interpreted by the scaling logic.","severity":"gotcha","affected_versions":"<0.1.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Remove `react-native-dotenv` from your project and replace its usage in your Babel configuration with `babel-plugin-dotenv-import`. Refer to the `react-native-size-matters` documentation for the correct setup of `babel-plugin-dotenv-import`.","cause":"This error typically occurs after upgrading to `react-native-size-matters@0.4.0` or higher, where the configuration for custom guideline sizes switched from `react-native-dotenv` to `babel-plugin-dotenv-import`.","error":"Module not found: Can't resolve 'react-native-dotenv' in ..."},{"fix":"Ensure you are wrapping your style definitions with `ScaledSheet.create({})` when using string-based scaling annotations (e.g., `'10@s'`). If the error persists, especially with older versions, upgrade `react-native-size-matters` to `v0.1.4` or higher.","cause":"This TypeScript error indicates you might be passing a string value (e.g., `'10@s'`) to a style property that expects a number, without using `ScaledSheet.create`. It can also occur in older versions (<0.1.4) even with `ScaledSheet` due to type inference issues.","error":"Type 'string' is not assignable to type 'number' in JSX attribute 'style'."},{"fix":"Always use `const styles = ScaledSheet.create({ /* ... */ })` when defining styles that include scaling annotations like `'10@s'`. Do not try to apply the annotations within a standard `StyleSheet.create` call.","cause":"This runtime error often means that you've attempted to use `ScaledSheet`'s annotation syntax directly within a `StyleSheet.create` call, or you've forgotten to wrap your style object with `ScaledSheet.create()` altogether.","error":"Invariant Violation: `style` prop value must be an object."}],"ecosystem":"npm"}