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.

pub package License: MIT

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

Made with love for the Flutter community

Libraries

layout_guard