layout_guard 0.0.1

Runtime layout overflow detector & visual debugger for Flutter. Automatically detects RenderFlex overflows with human-readable fix suggestions.

Layout Guard

Runtime Layout Debugger for Flutter

A runtime layout overflow detector & visual debugger for Flutter applications that automatically detects and highlights layout issues with human-readable fix suggestions.

---

Problem

Flutter developers frequently face layout issues like:

• RenderFlex overflowed by XX pixels
• Widgets breaking only on:
  • Small screen devices
  • Large accessibility font sizes
  • Different languages (long text / RTL)
• Issues that are hard to reproduce during development

These errors often appear late in testing or after release.

---

Solution

Layout Guard is a runtime layout overflow detector that:

• Automatically detects RenderFlex overflows and unbounded constraints
• Visually highlights problematic widgets on screen
• Provides fix suggestions in human-readable format
• Works at runtime without requiring DevTools
• Zero code changes to existing widgets

---

Getting Started

Installation

Add to your pubspec.yaml:

dependencies:
  layout_guard: ^0.0.1

Or install via command line:

flutter pub add layout_guard

Basic Usage

Wrap your app with LayoutGuard:

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

void main() {
  runApp(
    LayoutGuard(
      child: MyApp(),
    ),
  );
}

That's it! Layout Guard will now automatically detect and display overflow errors.

---

Features

Automatic Overflow Detection

Layout Guard automatically captures:

• RenderFlex horizontal overflows
• RenderFlex vertical overflows
• Exact pixel overflow amounts
• Widget tree locations

Visual Debugging

When an overflow is detected, you'll see:

• A visual overlay at the bottom-right of your screen
• The exact overflow amount in pixels
• The direction of overflow (horizontal/vertical)
• Navigation between multiple overflow errors

Smart Fix Suggestions

Get actionable suggestions based on the overflow type:

For horizontal overflows:

• Wrap your Row in a Flexible or Expanded widget
• Use SingleChildScrollView with horizontal scroll
• Replace Row with Wrap widget
• Reduce widget sizes or font sizes

For vertical overflows:

• Wrap your Column in a Flexible or Expanded widget
• Use SingleChildScrollView with vertical scroll
• Replace Column with ListView
• Reduce widget heights or padding

---

Usage Examples

Basic Configuration

LayoutGuard(
  child: MyApp(),
  // Show visual overlay (default: true)
  showOverlay: true,
  // Enable detection (default: true)
  enabled: true,
  // Print errors to console (default: true)
  printErrors: true,
)

Custom Callback

Get notified when overflows are detected:

LayoutGuard(
  child: MyApp(),
  onOverflowDetected: (OverflowInfo info) {
    print('Overflow detected: ${info.overflowPixels}px');
    // Send to analytics, logging service, etc.
  },
)

Custom Overlay Color

LayoutGuard(
  child: MyApp(),
  overlayColor: Colors.orange,
)

Debug-Only Mode

Enable only in debug builds:

import 'package:flutter/foundation.dart';

LayoutGuard(
  child: MyApp(),
  enabled: kDebugMode, // Only in debug mode
)

Disable Overlay, Keep Detection

LayoutGuard(
  child: MyApp(),
  showOverlay: false, // No visual overlay
  printErrors: true,  // Still logs to console
  onOverflowDetected: (info) {
    // Custom handling
  },
)

---

Real-World Example

Here's a typical layout issue that Layout Guard catches:

// This will overflow on small devices
Row(
  children: [
    Container(width: 200, child: Text('Item 1')),
    Container(width: 200, child: Text('Item 2')),
    Container(width: 200, child: Text('Item 3')),
  ],
)

Layout Guard will:

1. Detect the overflow
2. Show the exact pixel amount
3. Suggest fixes like:
   • "Wrap your Row in a Flexible or Expanded widget"
   • "Use SingleChildScrollView with horizontal scroll"
   • "Replace Row with Wrap widget"

---

Why Layout Guard is Unique

Unlike other debugging tools:

Feature	DevTools	Layout Guard
Runtime detection	External	In-app
Visual highlights	No	Yes
Fix suggestions	No	Yes
Zero setup	Requires connection	One widget wrap
Works on device	Limited	Full support

---

API Reference

LayoutGuard

Main widget that wraps your app to enable overflow detection.

Property	Type	Default	Description
child	Widget	required	Your root app widget
enabled	bool	true	Enable/disable detection
showOverlay	bool	true	Show visual debug overlay
printErrors	bool	true	Print errors to console
overlayColor	Color	Colors.red	Color for overlay highlights
onOverflowDetected	OverflowCallback?	null	Callback when overflow detected

OverflowInfo

Contains information about a detected overflow.

Property	Type	Description
message	String	Original error message
overflowPixels	double	Amount of overflow in pixels
overflowDirection	Axis?	Horizontal or vertical
timestamp	DateTime	When error was detected
fixSuggestions	List<String>	Human-readable fix suggestions

Methods

// Get short description
String shortDescription = overflowInfo.shortDescription;
// Output: "Overflow: 42.5px (horizontal)"

// Get all fix suggestions
List<String> suggestions = overflowInfo.fixSuggestions;

---

Testing

Layout Guard is designed to work seamlessly in tests:

testWidgets('app works with LayoutGuard', (tester) async {
  await tester.pumpWidget(
    LayoutGuard(
      child: MyApp(),
    ),
  );
  
  expect(find.byType(MyApp), findsOneWidget);
});

To disable in tests:

LayoutGuard(
  enabled: false,
  child: MyApp(),
)

---

Performance

Layout Guard is designed to be lightweight:

• Minimal overhead - Only activates when errors occur
• No production impact - Easily disabled with enabled: false
• Efficient rendering - Custom render objects for visual feedback

---

Contributing

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

---

License

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

---

Additional Resources

• Flutter Layout Documentation
• Understanding Constraints
• Common Layout Errors

---

Made with love for the Flutter community