debug_layout_hud 0.0.1

A debug-only, floating HUD overlay for Flutter that shows live screen size, custom responsive breakpoints, text scale and text direction — right on device or simulator, without opening Flutter DevTool [...]

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.

Status: pre-release (0.0.1) — not yet published to pub.dev.

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 (once published to pub.dev):

dependencies:
  debug_layout_hud: ^0.0.1

Until then, depend on it locally or via git:

dependencies:
  debug_layout_hud:
    path: ../debug_layout_hud

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

Parameter	Type	Default	Description
child	Widget	required	The rest of the app.
enabled	bool	true	Master switch — pass kDebugMode.
position	HudPosition	bottomRight	Which corner the HUD is anchored to.
breakpoints	List<BreakpointRule>	kDefaultBreakpoints	Named breakpoints, any order.
initiallyExpanded	bool	true	Whether the HUD starts expanded or collapsed.

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.

Roadmap to publish

• ❌ Update homepage / repository / issue_tracker in pubspec.yaml to your real GitHub repo URL.
• ❌ flutter pub get
• ❌ flutter analyze
• ❌ flutter test
• ❌ flutter pub publish --dry-run
• ❌ flutter pub publish

License

MIT — see LICENSE.