debug_layout_hud

A tiny, debug-only floating overlay (HUD) for Flutter that shows live layout metrics — screen size, custom responsive breakpoints, text scale, and text direction — directly on a real device or simulator, with no DevTools, no USB cable, and no extra app connection required.

Why this instead of DevTools / a grid overlay?

• Existing tools are either heavy (DevTools extensions, need the device tethered to a computer) or blunt (a full-screen grid you can't read numbers off of).
• debug_layout_hud shows compact, central metrics you can glance at while holding the phone in your hand: current width × height, which of your own named breakpoints is active, the effective text scale, and whether the app is currently LTR or RTL.
• It's 3 lines of code inside MaterialApp.builder — no wrapping every screen, no extra dependency wiring.

Features

• Live dimension tracking — reads MediaQuery.sizeOf(context), so the HUD (and only the HUD) rebuilds when the screen size actually changes, not on every unrelated MediaQuery change.
• Custom breakpoint resolution — pass your own named breakpoints (mobile / tablet / desktop, or whatever your design system calls them) via BreakpointRule; order doesn't matter, the resolver sorts internally.
• Typography & accessibility awareness — shows the live text scale factor and current Directionality, so RTL/LTR mirroring bugs are obvious immediately.
• Collapsible — one tap shrinks it to a small HUD badge so it never blocks the UI you're trying to test.
• Zero production footprint — guarded by enabled (wire it to kDebugMode) and kReleaseMode internally. When off, build() returns child straight through: no Stack, no extra widgets, no MediaQuery listeners.

Getting started

Add the dependency:

dependencies:
  debug_layout_hud: ^0.0.3

Usage

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:debug_layout_hud/debug_layout_hud.dart';

void main() => runApp(const MyApp());

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, child) => DebugLayoutHud(
        enabled: kDebugMode,
        position: HudPosition.bottomRight,
        breakpoints: const [
          BreakpointRule(name: 'compact', max: 600),
          BreakpointRule(name: 'medium', max: 900),
          BreakpointRule(name: 'expanded', max: double.infinity),
        ],
        child: child ?? const SizedBox.shrink(),
      ),
      home: const Scaffold(
        body: Center(child: Text('Hello Responsive World')),
      ),
    );
  }
}

See example/lib/main.dart for a full runnable app.

API

DebugLayoutHud

BreakpointRule({required String name, required double max})

A single named breakpoint, matched when the screen width is <= max.

BreakpointResolver(List<BreakpointRule> rules)

resolve(double width) -> String — returns the name of the smallest rule covering width. Rules do not need to be pre-sorted.

License

MIT — see LICENSE.