react-native-responsive-layout-kit

A lightweight, type-safe, cross-platform responsive UI and scaling engine for React Native with zero native dependencies.

Built for modern React Native apps, react-native-responsive-layout-kit provides pure JavaScript/TypeScript scaling formulas, responsive hooks, and a 12-column Flexbox grid system that works seamlessly across phones, tablets, foldables, split-screen modes, and landscape orientations.

✨ Features

• 📱 Cross-Platform & Universal: Works uniformly on iOS, Android, Tablets, Foldables, and Split-screen windows.
• ⚡ Zero Native Code: 100% pure TypeScript. Zero native dependencies, zero linking, and zero build headaches.
• 🚀 Expo & New Architecture Ready: Fully compatible with Expo Go, Expo EAS, React Native CLI, and React Native New Architecture (TurboModules & Fabric).
• 📐 Predictable Scale Engine: Precision mathematical scaling for widths, heights, margins, and paddings (scale, verticalScale, moderateScale, moderateVerticalScale).
• 🔠 Accessibility-Safe Typography: Responsive font scaling with responsiveFontSize that moderates tablet enlargement while fully respecting system accessibility settings.
• 🔄 Reactive Hooks: Hooks (useResponsive, useOrientation, useBreakpoint, useResponsiveValue) that automatically update on window resizing and screen rotation without memory leaks.
• 🍱 12-Column Responsive Grid: Flexbox <Row /> and <Col /> components with gutter management, breakpoint spans (xs, sm, md, lg, xl), and column offsets.
• 🛡️ Strict Type Safety: Fully typed with TypeScript strict mode, comprehensive autocomplete, and exported interfaces.
• 🪶 Tree-Shakeable & Lightweight: Zero external runtime dependencies.

📦 Installation

npm install react-native-responsive-layout-kit

or with Yarn:

yarn add react-native-responsive-layout-kit

Note: No native pod installation or linking is required.

⚡ Quick Start

import React from 'react';
import { View, Text, StyleSheet } from 'react-native';
import {
  scale,
  verticalScale,
  moderateScale,
  responsiveFontSize,
  useResponsive,
  Row,
  Col,
} from 'react-native-responsive-layout-kit';

export default function App() {
  const { isTablet, orientation, breakpoint } = useResponsive();

  return (
    <View style={styles.container}>
      <Text style={styles.heading}>Welcome to Responsive Kit</Text>
      <Text style={styles.subheading}>
        Active: {breakpoint.toUpperCase()} ({orientation}) •{' '}
        {isTablet ? 'Tablet' : 'Phone'}
      </Text>

      {/* 12-Column Responsive Grid */}
      <Row spacing={16} verticalSpacing={16}>
        <Col xs={12} md={6}>
          <View style={styles.card}>
            <Text style={styles.cardTitle}>Column 1</Text>
          </View>
        </Col>

        <Col xs={12} md={6}>
          <View style={styles.card}>
            <Text style={styles.cardTitle}>Column 2</Text>
          </View>
        </Col>
      </Row>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    paddingHorizontal: scale(20),
    paddingVertical: verticalScale(24),
    backgroundColor: '#0F172A',
  },
  heading: {
    fontSize: responsiveFontSize(24),
    fontWeight: 'bold',
    color: '#FFFFFF',
    marginBottom: verticalScale(8),
  },
  subheading: {
    fontSize: responsiveFontSize(14),
    color: '#94A3B8',
    marginBottom: verticalScale(20),
  },
  card: {
    backgroundColor: '#1E293B',
    padding: moderateScale(16),
    borderRadius: moderateScale(8),
  },
  cardTitle: {
    color: '#F8FAFC',
    fontSize: responsiveFontSize(16),
  },
});

⚙️ Configuration

react-native-responsive-layout-kit is pre-configured with industry-standard base dimensions (iPhone X/11/12 standard: 375 x 812).

You can customize base dimensions, breakpoint thresholds, and moderate scaling factors at your app's entry point using configureResponsive():

import { configureResponsive } from 'react-native-responsive-layout-kit';

configureResponsive({
  baseWidth: 375, // Your Figma/design base width
  baseHeight: 812, // Your Figma/design base height
  defaultModerateFactor: 0.5,
  tabletBreakpoint: 768,
  smallDeviceBreakpoint: 360,
  breakpoints: {
    xs: 0,
    sm: 360,
    md: 768,
    lg: 1024,
    xl: 1280,
  },
});

📖 API Reference

1. Scaling Functions

scale(size: number, customWidth?: number): number

Calculates linearly scaled horizontal dimension proportional to current screen width.

• Formula: (windowWidth / baseWidth) * size
• When to use: Horizontal dimensions like width, marginLeft, marginRight, paddingHorizontal.
• When NOT to use: Font sizes, border radii, or vertical heights.

const boxWidth = scale(150);

verticalScale(size: number, customHeight?: number): number

Calculates linearly scaled vertical dimension proportional to current screen height.

• Formula: (windowHeight / baseHeight) * size
• When to use: Vertical dimensions like height, marginTop, marginBottom, paddingVertical.
• When NOT to use: Horizontal paddings or font sizes.

const headerHeight = verticalScale(60);

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

Moderately scales a horizontal dimension with dampening to prevent over-scaling on tablets.

• Formula: size + (scale(size) - size) * factor
• Parameters:
  • size (number): Base dimension.
  • factor (number, optional): Factor between 0 (no scaling) and 1 (linear scaling). Defaults to 0.5.
• When to use: borderRadius, icon sizes, card padding, horizontal elements needing subtle scaling.
• When NOT to use: Exact full-width elements where linear percentage or flex is intended.

const iconSize = moderateScale(24);
const cardPadding = moderateScale(16, 0.3); // 30% scale intensity

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

Moderately scales a vertical dimension with dampening.

• Formula: size + (verticalScale(size) - size) * factor
• When to use: Vertical spacers and paddings that should scale gently across device heights.

const itemSpacing = moderateVerticalScale(12, 0.4);

responsiveFontSize(size: number, options?: ResponsiveFontSizeOptions, customWidth?: number): number

Calculates typography size adapting to screen width while honoring system accessibility font scale without distortion.

• Parameters:
  • size (number): Base font size in points.
  • options.factor (number, optional): Moderate scaling factor (default: 0.35).
  • options.maxFontSizeMultiplier (number, optional): Optional upper ceiling for accessibility font multiplier to prevent layout clipping.
• When to use: All text fontSize styling.
• When NOT to use: Layout widths or heights.

const title = responsiveFontSize(24);
const body = responsiveFontSize(16, { factor: 0.25 });
const clamped = responsiveFontSize(18, { maxFontSizeMultiplier: 1.5 });

2. Responsive React Hooks

useResponsive(): ResponsiveState

Primary hook subscribing to window dimension changes and returning reactive device info and scaling helpers.

const {
  width,
  height,
  isPortrait,
  isLandscape,
  isTablet,
  isSmallDevice,
  breakpoint,
  orientation,
  fontScale,
  pixelRatio,
  scale,
  verticalScale,
  moderateScale,
  moderateVerticalScale,
  responsiveFontSize,
} = useResponsive();

useOrientation(): { orientation, isPortrait, isLandscape }

Returns current window orientation. Updates automatically on device rotation.

const { orientation, isPortrait, isLandscape } = useOrientation();

useBreakpoint(): Breakpoint

Returns the active breakpoint tier ('xs' | 'sm' | 'md' | 'lg' | 'xl').

const breakpoint = useBreakpoint();
if (breakpoint === 'md' || breakpoint === 'lg') {
  // Tablet layout
}

useResponsiveValue<T>(input: ResponsiveValueInput<T>, defaultValue?: T): T

Selects a responsive value according to the current breakpoint using mobile-first fallback.

const numColumns = useResponsiveValue({
  xs: 1,
  md: 2,
  lg: 3,
});

const padding = useResponsiveValue((bp) => (bp === 'xs' ? 12 : 24));

3. Grid Components

<Row />

Flexbox row container that coordinates with nested <Col /> components to provide seamless gutters without horizontal overflow.

| Prop | Type | Default | Description | | :---------------- | :---------------------------------------------------------------------------------------------- | :------------- | :--------------------------------------- | | spacing | number | 0 | Horizontal gutter between columns in DP. | | verticalSpacing | number | spacing | Vertical gutter between row items in DP. | | align | 'flex-start' \| 'flex-end' \| 'center' \| 'stretch' \| 'baseline' | 'flex-start' | Flexbox alignItems. | | justify | 'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-around' \| 'space-evenly' | 'flex-start' | Flexbox justifyContent. | | wrap | boolean | true | Whether columns wrap onto multiple rows. | | style | StyleProp<ViewStyle> | undefined | Custom style overrides. | | testID | string | undefined | Test identifier. |

<Col />

12-column grid item component.

| Prop | Type | Description | | :--------------------------------------------------------- | :--------------------- | :------------------------------------------------ | | xs | 1..12 | Column span on extra-small screens (<360dp). | | sm | 1..12 | Column span on small screens (>=360dp). | | md | 1..12 | Column span on medium/tablet screens (>=768dp). | | lg | 1..12 | Column span on large screens (>=1024dp). | | xl | 1..12 | Column span on extra-large screens (>=1280dp). | | offset | 0..11 | Default column offset. | | xsOffset, smOffset, mdOffset, lgOffset, xlOffset | 0..11 | Breakpoint-specific column offsets. | | style | StyleProp<ViewStyle> | Custom style overrides. |

📱 Responsive Grid Example

<Row spacing={16} verticalSpacing={16} align="center">
  {/* Full-width on mobile (12 cols), half-width on tablet (6 cols), 1/3-width on desktop (4 cols) */}
  <Col xs={12} md={6} lg={4}>
    <Card title="Feature 1" />
  </Col>

  <Col xs={12} md={6} lg={4}>
    <Card title="Feature 2" />
  </Col>

  <Col xs={12} md={12} lg={4}>
    <Card title="Feature 3" />
  </Col>
</Row>

💡 Best Practices: Avoid Over-Scaling

A common mistake in React Native responsive design is linearly scaling typography on tablets. A 16pt font scaled linearly on a 1024dp iPad becomes 43pt, which degrades UX.

❌ DON'T:
fontSize: scale(16)            // Becomes huge on tablets (16 -> 43.6)

✅ DO:
fontSize: responsiveFontSize(16) // Subtly scales with typography hierarchy (16 -> 21)
fontSize: moderateScale(16, 0.3) // Custom controlled factor

| Use Case | Recommended API | | :------------------------------------- | :--------------------- | | Screen width proportional elements | scale() | | Screen height proportional spacers | verticalScale() | | Paddings, margins, border radii, icons | moderateScale() | | Typography / Headings / Paragraphs | responsiveFontSize() | | Multi-column responsive layout | <Row /> & <Col /> | | Breakpoint-dependent props | useResponsiveValue() |

♿ Accessibility

react-native-responsive-layout-kit is built to respect accessibility settings:

• responsiveFontSize factors in PixelRatio.getFontScale().
• Does not disable accessibility or use allowFontScaling={false}.
• Supports maxFontSizeMultiplier to ensure typography scales safely without layout clipping.

🚀 Expo & Compatibility

• Expo: Fully compatible with Expo Go and Expo Bare workflows. Zero config plugins needed.
• React Native CLI: Compatible with all supported versions (>=0.65.0).
• React Native New Architecture: 100% compatible with TurboModules and Fabric.
• React Native Web: Pure JavaScript components work seamlessly across web targets.

📄 License

MIT © react-native-responsive-layout-kit contributors