React Native UI Scaling Utility

Common errors

• Module not found: Can't resolve 'react-native-dotenv' in ...

  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`.
  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`.

• Type 'string' is not assignable to type 'number' in JSX attribute 'style'.

  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.
  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.

• Invariant Violation: `style` prop value must be an object.

  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.
  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.

Warnings

• breaking 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`.
  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.
• gotcha 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`.
  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.
• gotcha 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.
  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.

Install

• npm install react-native-size-matters npm
• yarn add react-native-size-matters yarn
• pnpm add react-native-size-matters pnpm

Imports

• scale, verticalScale, moderateScale
  wrong:

  import scale from 'react-native-size-matters';
  // Or for CJS (less common in modern RN):
  const scale = require('react-native-size-matters').scale;

  correct:

  import { scale, verticalScale, moderateScale } from 'react-native-size-matters';

  These are named exports for the primary scaling functions. Shorthand aliases like `s`, `vs`, `ms`, `mvs` are also available as named exports.
• ScaledSheet
  wrong:

  import ScaledSheet from 'react-native-size-matters';

  correct:

  import { ScaledSheet } from 'react-native-size-matters';

  `ScaledSheet` is a named export that allows defining styles with scaling annotations.
• All exports (CommonJS)

  const { scale, verticalScale, ScaledSheet } = require('react-native-size-matters');

  While ES modules (`import`) are standard in modern React Native, CommonJS `require` can still be used to access all exports in some environments.

Quickstart

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.

import React from 'react';
import { View, Text, StyleSheet } from 'react-native';
import { scale, verticalScale, moderateScale, ScaledSheet } from 'react-native-size-matters';

const App = () => {
  return (
    <View style={styles.container}>
      <Text style={styles.scaledText}>Scaled Text (Width based: 20@s)</Text>
      <View style={styles.box}>
        <Text style={styles.boxText}>Box</Text>
      </View>
      <Text style={{ fontSize: moderateScale(16, 0.3), marginTop: verticalScale(10) }}>
        Moderately Scaled Text
      </Text>
      <Text style={rawStyles.normalText}>Normal Text (No Scaling)</Text>
    </View>
  );
};

const rawStyles = StyleSheet.create({
  normalText: {
    fontSize: 16,
    color: '#666',
    marginTop: 20
  }
});

const styles = ScaledSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#F5FCFF',
    padding: '20@ms'
  },
  scaledText: {
    fontSize: '20@s',
    color: '#333',
    marginBottom: '10@vs'
  },
  box: {
    width: '150@s',
    height: '100@vs',
    backgroundColor: 'lightblue',
    justifyContent: 'center',
    alignItems: 'center',
    borderRadius: '8@ms0.3',
    marginVertical: '20@vs'
  },
  boxText: {
    fontSize: '18@ms',
    color: 'darkblue'
  }
});

export default App;