react-screenutil

A React/TypeScript implementation inspired by Flutter's flutter_screenutil package for creating responsive UIs that adapt seamlessly across different screen sizes.

🚀 Features

• 🎨 Flutter-like syntax - Use .w, .h, .sp, .r on numbers
• 📱 Automatic scaling based on design size
• 🔄 Zero re-renders option with direct DOM manipulation
• 💪 Full TypeScript support
• ⚡ Lightweight with no dependencies
• 🌐 SSR-safe

📦 Installation

npm install react-screenutil
# or
yarn add react-screenutil
# or
pnpm add react-screenutil

🎯 Quick Start

1. Initialize ScreenUtil

Wrap your app with the provider (optional, for automatic re-renders):

import { ScreenUtilProvider } from "react-screenutil";

function App() {
  return (
    <ScreenUtilProvider designWidth={375} designHeight={812}>
      <YourApp />
    </ScreenUtilProvider>
  );
}

2. Use Responsive Values

import "react-screenutil"; // Enable .w, .h, .sp, .r extensions

function MyComponent() {
  return (
    <div
      style={{
        width: `${(300).w}px`,
        height: `${(200).h}px`,
        fontSize: `${(16).sp}px`,
        borderRadius: `${(12).r}px`,
      }}
    >
      Responsive Content
    </div>
  );
}

📚 API Reference

Extension Methods

| Method | Description | Example | | ------ | --------------- | --------- | | .w | Scale width | (100).w | | .h | Scale height | (50).h | | .sp | Scale font size | (16).sp | | .r | Scale radius | (8).r |

ScreenUtil Class

import { ScreenUtil } from "react-screenutil";

// Initialize
ScreenUtil.init({ designWidth: 375, designHeight: 812 });

// Get dimensions
ScreenUtil.width; // Current screen width
ScreenUtil.height; // Current screen height

// Manual scaling
ScreenUtil.setWidth(100);
ScreenUtil.setHeight(50);
ScreenUtil.setSp(16);
ScreenUtil.setRadius(8);

// Get scale factors
ScreenUtil.scaleWidth;
ScreenUtil.scaleHeight;

React Context (with re-renders)

import { useScreenUtil } from "react-screenutil";

function MyComponent() {
  const { width, height } = useScreenUtil();

  return (
    <div>
      Screen: {width} × {height}
    </div>
  );
}

Direct DOM Manipulation (no re-renders)

import { ScreenUtil } from "react-screenutil";
import { useEffect, useRef } from "react";

function MyComponent() {
  const textRef = useRef<HTMLParagraphElement>(null);

  useEffect(() => {
    const updateSize = () => {
      if (textRef.current) {
        textRef.current.style.fontSize = `${(16).sp}px`;
      }
    };

    updateSize();
    window.addEventListener("resize", updateSize);
    return () => window.removeEventListener("resize", updateSize);
  }, []);

  return <p ref={textRef}>Responsive text</p>;
}

💡 Usage Examples

Responsive Card

<div
  style={{
    width: `${(300).w}px`,
    padding: `${(16).w}px`,
    borderRadius: `${(12).r}px`,
    boxShadow: "0 2px 8px rgba(0,0,0,0.1)",
  }}
>
  <h2 style={{ fontSize: `${(20).sp}px` }}>Title</h2>
  <p style={{ fontSize: `${(14).sp}px` }}>Content</p>
</div>

Responsive Grid

<div
  style={{
    display: "grid",
    gridTemplateColumns: `repeat(auto-fit, minmax(${(150).w}px, 1fr))`,
    gap: `${(16).w}px`,
  }}
>
  {items.map((item) => (
    <GridItem key={item.id} {...item} />
  ))}
</div>

🎨 Design Size Recommendations

| Device | Width | Height | Use Case | | ------------- | ----- | ------ | ------------------------ | | iPhone 11 Pro | 375 | 812 | Modern iOS (recommended) | | Android | 360 | 800 | Android devices | | iPad | 768 | 1024 | Tablets | | Desktop | 1920 | 1080 | Desktop apps |

Tip: Use mobile-first design sizes (375×812) so elements scale UP on larger screens.

🔧 Configuration

ScreenUtil.init({
  designWidth: 375, // Your design mockup width
  designHeight: 812, // Your design mockup height
  splitScreenMode: false, // Reserved for future use
});

📖 How It Works

The utility calculates scale factors based on your design size:

scaledValue = designValue × (currentScreenWidth / designWidth)

Example:

• Design width: 375px
• Current screen: 1366px
• Scale factor: 1366 / 375 = 3.64
• (100).w = 100 × 3.64 = 364px

🤝 Contributing

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

📄 License

MIT © [Your Name]

🙏 Acknowledgments

Inspired by Flutter's flutter_screenutil package.