react-native-scaled-sizes

A dependency-free React Native utility library for scaling your app UI across different sized devices. Design on one device, scale perfectly to all.

✨ Features

• 📱 Universal scaling - Works on iOS, Android, and tablets
• 🎯 Zero dependencies - Only peer dependency is react-native
• 📐 Multiple scaling strategies - Horizontal, vertical, moderate, and uniform scaling
• ⚡ Performance optimized - Pre-computed values and memoization
• 🔤 TypeScript support - Full type definitions included
• 📏 Tailwind-like presets - Pre-computed size styles ready to use

📦 Installation

# npm
npm install react-native-scaled-sizes

# yarn
yarn add react-native-scaled-sizes

# pnpm
pnpm add react-native-scaled-sizes

🚀 Quick Start

import { configure, scaledSizes, scaleText } from 'react-native-scaled-sizes';
import { View, Text } from 'react-native';

// Optional: Configure base dimensions (call once in App.tsx)
// Default is iPhone 17 Pro: 402x874
configure({ width: 375, height: 812 }); // Example: iPhone X design

const MyComponent = () => (
  <View style={scaledSizes.uniformSize12}>
    <Text style={{ fontSize: scaleText(16), lineHeight: scaleText(24) }}>
      Hello World
    </Text>
  </View>
);

⚙️ Configuration

Configure the library once in your app's entry point to match your design's base dimensions:

// App.tsx or index.js
import { configure } from 'react-native-scaled-sizes';

// Set your Figma/design artboard dimensions
configure({ 
  width: 375,   // Design width (default: 402)
  height: 812   // Design height (default: 874)
});

Configuration API

configure(config: ScalingConfig): void

Set custom base dimensions for scaling calculations.

configure({ width: 375, height: 812 });

getConfig(): { width: number; height: number; isConfigured: boolean }

Get current configuration values.

const config = getConfig();
console.log(config); // { width: 375, height: 812, isConfigured: true }

resetConfig(): void

Reset to default dimensions (402x874).

resetConfig();

📐 Base Dimensions

The library uses iPhone 17 Pro dimensions as the design reference:

• Width: 402px
• Height: 874px

All scaling is calculated relative to these base dimensions.

🛠 API Reference

Core Scaling Functions

scale(size: number): number

Scales horizontally based on screen width. Best for horizontal spacing, widths, and horizontal paddings.

scale(100) // Returns scaled width

verticalScale(size: number): number

Scales vertically based on screen height. Best for vertical spacing, heights, and vertical paddings.

verticalScale(100) // Returns scaled height

moderateScale(size: number, factor?: number): number

Provides a more gradual scaling than linear. The factor parameter (default: 0.5) controls how much scaling is applied.

moderateScale(20)      // 50% of the scaling
moderateScale(20, 0.3) // 30% of the scaling

moderateVerticalScale(size: number, factor?: number): number

Same as moderateScale but for vertical dimensions.

moderateVerticalScale(20) // Moderately scaled vertical size

scaleSize(size: number): number

Uniform scaling based on the minimum of width and height ratios. Uses memoization for optimal performance.

scaleSize(32) // Uniformly scaled size

Text Scaling

scaleText(size: number): number

Adaptive text scaling that uses different factors for larger and smaller devices. Best used for font sizes and line heights.

scaleText(16) // Adaptively scaled font size

Complete Text Scaling Example:

import { scaleText, moderateScale } from 'react-native-scaled-sizes';
import { Text as RNText } from 'react-native';

// Helper to scale text styles (fontSize and lineHeight)
const scaleTextStyle = (style: any, defaults = { fontSize: 16, lineHeight: 24 }) => {
  if (!style) {
    return {
      fontSize: scaleText(defaults.fontSize),
      lineHeight: scaleText(defaults.lineHeight)
    };
  }
  
  const scaledStyle = { ...style };
  
  // Apply and scale fontSize
  if (!scaledStyle.fontSize) scaledStyle.fontSize = defaults.fontSize;
  if (typeof scaledStyle.fontSize === 'number') {
    scaledStyle.fontSize = scaleText(scaledStyle.fontSize);
  }
  
  // Apply and scale lineHeight
  if (!scaledStyle.lineHeight) scaledStyle.lineHeight = defaults.lineHeight;
  if (typeof scaledStyle.lineHeight === 'number') {
    scaledStyle.lineHeight = scaleText(scaledStyle.lineHeight);
  }
  
  return scaledStyle;
};

// Custom Text component with automatic scaling
const Text = ({ style, disableScaling = false, ...props }) => {
  const scaledStyle = disableScaling ? style : scaleTextStyle(style);
  return <RNText style={scaledStyle} {...props} />;
};

// Usage
<Text>Default text (16/24)</Text>
<Text style={{ fontSize: 20, lineHeight: 28 }}>Larger text</Text>
<Text disableScaling>No scaling applied</Text>

scaleFontSize(size: number, maxScale?: number): number

Scales font size with accessibility support. The maxScale parameter (default: 1.5) limits maximum scaling.

scaleFontSize(16)     // Scaled with 1.5x max
scaleFontSize(16, 2)  // Scaled with 2x max

scaleHeight(size: number): number

Scales size based on screen height.

scaleHeight(100) // Returns scaled height

scaleLongDimension(size: number): number

Scales based on the longer dimension (works in both portrait and landscape orientations).

scaleLongDimension(100) // Returns scaled size based on longer dimension

Utility Functions

createScaledSize(width: number, height?: number)

Creates a memoized StyleSheet with scaled dimensions.

const { size } = createScaledSize(100, 50).size;
// { width: scale(100), height: verticalScale(50) }

Pre-computed Values

scaledSizes

Pre-computed StyleSheet with Tailwind-like sizing (following Tailwind's 4px spacing scale).

import { scaledSizes } from 'react-native-scaled-sizes';

<View style={scaledSizes.uniformSize12} /> // 48px × 48px, uniformly scaled
<View style={scaledSizes.size10} />        // 40px × 40px, horizontally scaled
<View style={scaledSizes.uniformW8} />     // width: 32px, uniformly scaled
<View style={scaledSizes.h12} />           // height: 48px, vertically scaled

Available prefixes:

• size* - Square sizes (width + height with scale)
• uniformSize* - Square sizes (width + height with scaleSize)
• moderateSize* - Square sizes (width + height with moderateScale)
• w* - Width only (with scale)
• uniformW* - Width only (with scaleSize)
• h* - Height only (with verticalScale)
• uniformH* - Height only (with scaleSize)
• minW* - Min width
• maxW* - Max width
• minH* - Min height
• maxH* - Max height

Short Aliases

For convenience, short aliases are also exported:

import { s, vs, ms, mvs } from 'react-native-scaled-sizes';

s(16)    // same as scale(16)
vs(16)   // same as verticalScale(16)
ms(16)   // same as moderateScale(16)
mvs(16)  // same as moderateVerticalScale(16)

💡 Usage Tips

When to use each function

| Function | Use Case | Example | |----------|----------|--------| | scaledSizes.uniformSize* | Pre-computed uniform sizes | <View style={scaledSizes.uniformSize12} /> | | scaledSizes.size* | Pre-computed horizontal sizes | <View style={scaledSizes.size10} /> | | scaleText | Font sizes & line heights | style={{ fontSize: scaleText(16) }} | | scale | Custom horizontal dimensions | width: scale(300) | | verticalScale | Custom vertical dimensions | height: verticalScale(200) | | moderateScale | Paddings, border radius | padding: moderateScale(16) | | scaleSize | Dynamic uniform scaling | const size = scaleSize(32) |

Performance Tips

1. Use scaledSizes StyleSheet for common dimensions:

   // ✅ Best - pre-computed StyleSheet (no runtime calculation)
   <View style={scaledSizes.uniformSize12} />
   <View style={scaledSizes.uniformW32} />
   <View style={scaledSizes.h16} />
      
   // ⚠️ Less optimal - calculates on every render
   <View style={{ width: scaleSize(48) }} />

2. Define scaled styles outside components:

   // ✅ Good - computed once at module load
   const styles = StyleSheet.create({
     container: {
       width: scale(300),
       height: verticalScale(200),
       padding: moderateScale(16)
     },
     text: {
       fontSize: scaleText(16),
       lineHeight: scaleText(24)
     }
   });
      
   // Use in component
   <View style={styles.container}>
     <Text style={styles.text}>Scaled text</Text>
   </View>

3. Combine with Tailwind/NativeWind:

   // Use scaledSizes alongside className
   <View className="bg-gray-900" style={scaledSizes.uniformSize16}>
     <Text className="text-white font-bold" style={{ fontSize: scaleText(18) }}>
       Responsive Text
     </Text>
   </View>

4. Built-in memoization:

   // scaleSize() caches results automatically
   const size = scaleSize(32); // Cached for reuse

📝 License

MIT © Zlvsky

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.