px_responsive #

A powerful tri-tier responsive design system for Flutter that automatically scales your UI across mobile, tablet, and desktop platforms based on your Figma/XD design specifications.

Table of Contents #

• Features
• Installation
• Quick Start
• How It Works
• API Reference
  • Core Extensions
  • Screen Percentage Extensions
  • Parent-Relative Extensions
  • Clamping Methods
  • Object Extensions
  • Global Getters
  • Global Functions
• Responsive Widgets
  • PxResponsiveBuilder
  • PxResponsiveValue
  • PxResponsiveVisibility
• Configuration Options
• Best Practices
• Ultra-Wide Screen Support
• Complete Example
• WASM Support
• License

Features #

• 🎯 Tri-Tier Scaling — Automatically switches between mobile, tablet, and desktop base designs
• 📐 Design-to-Code Mapping — Use exact values from your Figma/XD designs
• 🔒 Safe Scaling — Built-in min/max constraints prevent layout breaking
• 📱 Device Detection — Simple isMobile, isTablet, isDesktop getters
• 🖥️ Ultra-Wide Support — Optional maxWidth cap for large displays
• 🧩 Rich Widget Library — Responsive builders, visibility controls, and value providers
• ✨ Intuitive API — Clean extension syntax (.w, .h, .sp, .r)
• 🌐 WASM Compatible — Pure Dart implementation, works everywhere Flutter runs

Installation #

Add px_responsive to your pubspec.yaml:

dependencies:
  px_responsive: ^0.0.1

Then run:

flutter pub get

Quick Start #

1. Wrap Your App #

Wrap your root widget with PxResponsiveWrapper and provide your design specifications:

import 'package:flutter/material.dart';
import 'package:px_responsive/px_responsive.dart';

void main() {
  runApp(
    PxResponsiveWrapper(
      config: const PxResponsiveConfig(
        // Your design tool's artboard sizes
        desktop: Size(1920, 1080),
        tablet: Size(834, 1194),
        mobile: Size(375, 812),
        
        // Breakpoints (when to switch layouts)
        mobileBreakpoint: 600,
        tabletBreakpoint: 1200,
      ),
      child: const MyApp(),
    ),
  );
}

2. Use Extensions in Your Widgets #

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Container(
      width: 200.w,              // Scaled width
      height: 150.h,             // Scaled height
      padding: EdgeInsets.all(16.r),  // Scaled padding
      child: Text(
        'Hello World',
        style: TextStyle(fontSize: 18.sp),  // Scaled font
      ),
    );
  }
}

3. Adapt to Device Types #

Widget build(BuildContext context) {
  if (isMobile) {
    return MobileLayout();
  } else if (isTablet) {
    return TabletLayout();
  } else {
    return DesktopLayout();
  }
}

How It Works #

The Scaling Formula #

When you use 200.w, the package calculates:

result = 200 × (currentScreenWidth ÷ activeBaseDesignWidth)

Automatic Base Switching #

The package automatically selects the appropriate base design based on screen width:

Visual Example #

Mobile Design (375px wide)          Your Phone (390px wide)
┌─────────────────┐                 ┌─────────────────┐
│  Button: 100px  │      →          │  Button: 104px  │
│  Font: 16px     │   Scaling       │  Font: 16.6px   │
└─────────────────┘                 └─────────────────┘

Scale Factor: 390 ÷ 375 = 1.04

API Reference #

Core Extensions #

These are the primary extensions you'll use most often.

Container(
  width: 300.w,                    // Scales with screen width
  height: 200.h,                   // Scales with screen height
  decoration: BoxDecoration(
    borderRadius: BorderRadius.circular(12.r),  // Uniform scaling
  ),
  child: Text(
    'Responsive Text',
    style: TextStyle(fontSize: 16.sp),  // Won't get too large
  ),
)

When to Use Each

Screen Percentage Extensions #

Use these when you want a percentage of the full screen.

Container(
  width: 80.wf,   // 80% of screen width
  height: 50.hf,  // 50% of screen height
  child: Text('Full-width card'),
)

Best Use Cases

• Full-width containers: 100.wf
• Half-screen layouts: 50.wf
• Modal dialogs: 90.wf width, 80.hf height
• Hero sections: 100.wf width, 60.hf height

Parent-Relative Extensions #

Use these when you need sizing relative to a parent widget, not the screen.

Setup Required: Wrap the parent with PxRelativeSizeProvider:

PxRelativeSizeProvider(
  child: Row(
    children: [
      Container(
        width: 30.wr(context),  // 30% of Row's width
        child: Sidebar(),
      ),
      Container(
        width: 70.wr(context),  // 70% of Row's width
        child: MainContent(),
      ),
    ],
  ),
)

Best Use Cases

• Split layouts within a container
• Proportional grid items
• Nested responsive layouts

Clamping Methods #

Prevent values from going too small or too large.

Container(
  // Width scales but never below 200 or above 500
  width: 300.wClamp(200, 500),
  
  child: Text(
    'Readable Text',
    // Font scales but stays between 14 and 22
    style: TextStyle(fontSize: 18.spClamp(14, 22)),
  ),
)

Best Use Cases

• Buttons that shouldn't be too small on tiny screens
• Text that must remain readable
• Images that shouldn't exceed a certain size
• Cards with minimum touch targets

Object Extensions #

Scale entire objects at once.

EdgeInsets Extensions

// All sides scale uniformly
padding: EdgeInsets.all(16).w

// Horizontal and vertical scale independently
padding: EdgeInsets.symmetric(
  horizontal: 20,
  vertical: 16,
).scaled

// Uniform scaling for symmetric padding
margin: EdgeInsets.all(12).r

Size Extensions

// Aspect-ratio aware scaling
Size imageSize = Size(400, 300).scaled;

// Square that stays square
Size avatarSize = Size(80, 80).r;

BorderRadius Extensions

decoration: BoxDecoration(
  borderRadius: BorderRadius.circular(16).r,
)

// Or with different corners
borderRadius: BorderRadius.only(
  topLeft: Radius.circular(20),
  topRight: Radius.circular(20),
).r

Global Getters #

Quick access to device information without calling PxResponsive().

// Simple boolean checks
if (isMobile) {
  return CompactView();
}

// Switch on device type
switch (deviceType) {
  case PxDeviceType.mobile:
    return MobileLayout();
  case PxDeviceType.tablet:
    return TabletLayout();
  case PxDeviceType.desktop:
    return DesktopLayout();
}

// Use dimensions directly
final isLandscape = screenWidth > screenHeight;

Global Functions #

responsiveValue

Returns different values based on device type.

T responsiveValue<T>({
  required T mobile,
  T? tablet,
  T? desktop,
})

// Different column counts
int columns = responsiveValue(
  mobile: 1,
  tablet: 2,
  desktop: 4,
);

// Different padding
double padding = responsiveValue(
  mobile: 16.0,
  tablet: 24.0,
  desktop: 32.0,
);

// Different widgets
Widget icon = responsiveValue(
  mobile: Icon(Icons.menu),
  desktop: Icon(Icons.dashboard),
);

Fallback Behavior:

• If tablet is null → uses mobile
• If desktop is null → uses tablet (or mobile if tablet is also null)

Responsive Widgets #

PxResponsiveBuilder #

Build completely different widget trees for each device type.

PxResponsiveBuilder(
  mobile: (context) => MobileLayout(),
  tablet: (context) => TabletLayout(),
  desktop: (context) => DesktopLayout(),
)

When to Use:

• Completely different layouts per device
• Different navigation patterns (drawer vs sidebar)
• Different component hierarchies

// Navigation example
PxResponsiveBuilder(
  mobile: (context) => Scaffold(
    drawer: NavigationDrawer(),
    body: Content(),
  ),
  desktop: (context) => Row(
    children: [
      SideNavigation(),
      Expanded(child: Content()),
    ],
  ),
)

PxResponsiveValue #

Provide different values and build with them.

PxResponsiveValue<int>(
  mobile: 1,
  tablet: 2,
  desktop: 4,
  builder: (context, columnCount) {
    return GridView.count(
      crossAxisCount: columnCount,
      children: items,
    );
  },
)

When to Use:

• Same widget structure, different parameters
• Grid layouts with varying columns
• Dynamic spacing or sizing

// Dynamic grid
PxResponsiveValue<int>(
  mobile: 2,
  tablet: 3,
  desktop: 5,
  builder: (context, columns) => GridView.builder(
    gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
      crossAxisCount: columns,
    ),
    itemBuilder: (context, index) => ProductCard(products[index]),
  ),
)

PxResponsiveVisibility #

Show or hide widgets based on device type.

Default Constructor

PxResponsiveVisibility(
  visibleOnMobile: false,
  visibleOnTablet: true,
  visibleOnDesktop: true,
  child: Sidebar(),
)

Named Constructors

// Sidebar only on desktop
PxResponsiveVisibility.desktop(
  child: Sidebar(),
)

// Mobile menu button
PxResponsiveVisibility.mobile(
  child: IconButton(
    icon: Icon(Icons.menu),
    onPressed: openDrawer,
  ),
)

// Show on tablet and up
PxResponsiveVisibility.tabletUp(
  child: ExtendedNavigation(),
  replacement: CompactNavigation(), // Shown when hidden
)

Options

PxResponsiveVisibility.desktop(
  maintainState: true,  // Keep sidebar state when switching to tablet
  child: Sidebar(),
  replacement: CollapsedSidebar(),
)

When to Use:

• Hiding navigation elements on mobile
• Showing/hiding sidebars
• Conditional feature visibility
• Progressive disclosure of UI elements

Configuration Options #

PxResponsiveConfig #

const PxResponsiveConfig({
  // Base design sizes from your design tool
  Size desktop = const Size(1920, 1080),
  Size tablet = const Size(834, 1194),
  Size mobile = const Size(375, 812),
  
  // Breakpoints
  double mobileBreakpoint = 600,    // Below this = mobile
  double tabletBreakpoint = 1200,   // Above this = desktop
  
  // Scaling constraints
  double? maxWidth,                 // Cap width for ultra-wide screens
  double? minScaleFactor = 0.5,     // Elements won't shrink below 50%
  double? maxScaleFactor = 2.0,     // Elements won't grow beyond 200%
  double? maxTextScaleFactor = 1.5, // Text won't grow beyond 150%
})

Common Design Sizes #

Configuration Examples #

Standard Setup

PxResponsiveConfig(
  desktop: Size(1440, 900),
  tablet: Size(768, 1024),
  mobile: Size(375, 812),
)

With Ultra-Wide Support

PxResponsiveConfig(
  desktop: Size(1920, 1080),
  tablet: Size(834, 1194),
  mobile: Size(375, 812),
  maxWidth: 1920,  // Content won't stretch beyond 1920px
)

Conservative Scaling

PxResponsiveConfig(
  desktop: Size(1920, 1080),
  tablet: Size(834, 1194),
  mobile: Size(375, 812),
  minScaleFactor: 0.8,      // Don't shrink too much
  maxScaleFactor: 1.5,      // Don't grow too much
  maxTextScaleFactor: 1.2,  // Keep text readable
)

Best Practices #

1. Match Your Design Tool #

Always use the exact artboard sizes from your design tool:

// If your Figma mobile frame is 390×844
mobile: Size(390, 844),

// If your XD desktop artboard is 1440×900
desktop: Size(1440, 900),

2. Use Appropriate Extensions #

// ✅ Good
width: 200.w,           // Horizontal → use .w
height: 100.h,          // Vertical → use .h
fontSize: 16.sp,        // Text → use .sp
borderRadius: 12.r,     // Radius → use .r

// ❌ Avoid
width: 200.h,           // Don't use .h for width
fontSize: 16.w,         // Don't use .w for fonts

3. Clamp Critical Values #

// Ensure buttons are always tappable (min 44px)
height: 48.hMin(44),

// Ensure text is always readable
fontSize: 14.spMin(12),

// Prevent images from getting too large
width: 400.wMax(500),

4. Use Device-Specific Values #

// Different spacing per device
padding: EdgeInsets.all(
  responsiveValue(mobile: 12, tablet: 16, desktop: 24).w
),

// Different layouts
crossAxisCount: responsiveValue(mobile: 2, tablet: 3, desktop: 4),

5. Combine Extensions Thoughtfully #

// Responsive padding with scaling
padding: EdgeInsets.symmetric(
  horizontal: responsiveValue(mobile: 16, tablet: 24, desktop: 32).w,
  vertical: responsiveValue(mobile: 12, tablet: 16, desktop: 20).h,
),

Ultra-Wide Screen Support #

On ultra-wide monitors (3840px+), UI elements can become excessively large. Use maxWidth to cap scaling:

Without maxWidth #

Screen: 3840px → Scale: 3840/1920 = 2.0×
A 200px button becomes 400px (too large!)

With maxWidth: 1920 #

Screen: 3840px → Effective: 1920px → Scale: 1.0×
A 200px button stays 200px (centered on screen)

Implementation #

PxResponsiveWrapper(
  config: PxResponsiveConfig(
    desktop: Size(1920, 1080),
    maxWidth: 1920,  // ← Add this
  ),
  child: MyApp(),
)

Centering Content #

When using maxWidth, center your content for the best appearance:

Scaffold(
  body: Center(
    child: ConstrainedBox(
      constraints: BoxConstraints(maxWidth: 1920),
      child: YourContent(),
    ),
  ),
)

Complete Example #

import 'package:flutter/material.dart';
import 'package:px_responsive/px_responsive.dart';

void main() {
  runApp(
    PxResponsiveWrapper(
      config: const PxResponsiveConfig(
        desktop: Size(1920, 1080),
        tablet: Size(834, 1194),
        mobile: Size(375, 812),
        maxWidth: 1920,
      ),
      child: const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: const HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(
          'px_responsive Demo',
          style: TextStyle(fontSize: 20.sp),
        ),
        // Show menu button only on mobile
        leading: PxResponsiveVisibility.mobile(
          child: IconButton(
            icon: const Icon(Icons.menu),
            onPressed: () {},
          ),
        ),
      ),
      body: Row(
        children: [
          // Sidebar only on desktop
          PxResponsiveVisibility.desktop(
            child: Container(
              width: 250.w,
              color: Colors.grey[200],
              child: const Center(child: Text('Sidebar')),
            ),
          ),
          
          // Main content
          Expanded(
            child: Padding(
              padding: EdgeInsets.all(
                responsiveValue(mobile: 16, tablet: 24, desktop: 32).w,
              ),
              child: PxResponsiveValue<int>(
                mobile: 1,
                tablet: 2,
                desktop: 3,
                builder: (context, columns) {
                  return GridView.builder(
                    gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
                      crossAxisCount: columns,
                      spacing: 16.w,
                      childAspectRatio: 1.2,
                    ),
                    itemCount: 9,
                    itemBuilder: (context, index) => Card(
                      child: Padding(
                        padding: EdgeInsets.all(16.r),
                        child: Column(
                          mainAxisAlignment: MainAxisAlignment.center,
                          children: [
                            Icon(Icons.star, size: 40.sp),
                            SizedBox(height: 8.h),
                            Text(
                              'Item $index',
                              style: TextStyle(fontSize: 16.sp),
                            ),
                          ],
                        ),
                      ),
                    ),
                  );
                },
              ),
            ),
          ),
        ],
      ),
      
      // Bottom navigation only on mobile
      bottomNavigationBar: PxResponsiveVisibility.mobile(
        child: BottomNavigationBar(
          items: const [
            BottomNavigationBarItem(icon: Icon(Icons.home), label: 'Home'),
            BottomNavigationBarItem(icon: Icon(Icons.search), label: 'Search'),
            BottomNavigationBarItem(icon: Icon(Icons.person), label: 'Profile'),
          ],
        ),
      ),
    );
  }
}

WASM Support #

This package is fully compatible with Flutter's WebAssembly (WASM) compilation target. It uses only:

• Pure Dart code
• Standard Flutter widgets
• No platform-specific plugins

Simply compile your Flutter web app to WASM as usual:

flutter build web --wasm

License #

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 About the Author #

Ibrahim El Mourchidi

Flutter & Firebase Developer • Cairo, Egypt

👥 Contributors #

We appreciate all contributions to this project!

Support #

If you find this package helpful, please give it a ⭐ on GitHub!

For bugs or feature requests, please open an issue.