flutter_ui_inspector

Debug-only UI inspection tools for Flutter. Inspect widget state, rebuild frequency, performance, and a floating panel without impacting release builds.

Why

Debugging UI issues is hard when you can’t see rebuild churn or widget state transitions. This package overlays lightweight badges and tools to surface that information in debug mode only.

Features

• Rebuild tracking badges per widget
• UI state badges (loading, error, empty, ready)
• Debug-only safety (no release impact)
• FPS / frame timing tracking
• Floating inspector panel with gesture activation
• Rebuild heatmap overlay

Screenshots

Without Inspector	With Inspector	Inspector Panel

Safety

• Guarded by kDebugMode and UiInspectorConfig.enabled
• No platform channels; Flutter-only
• Nothing activates in release mode

Installation

dependencies:
  flutter_ui_inspector: ^1.0.0

Quick Start

Track state + rebuilds

import 'package:flutter_ui_inspector/flutter_ui_inspector.dart';

class UserListView extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return UiInspector(
      name: 'UserList',
      loading: true, // or from your state
      error: false,
      empty: false,
      child: ListView(children: const [Text('Item')]),
    );
  }
}

Track rebuilds only

RebuildTracker(
  name: 'ProfileCard',
  child: ProfileCard(),
);

Configuration

UiInspectorConfig.enabled = true;
UiInspectorConfig.showRebuildCount = true;
UiInspectorConfig.showStateBadge = true;
UiInspectorConfig.trackPerformance = false;
UiInspectorConfig.enableHeatmap = false;
UiInspectorConfig.rebuildWarningThreshold = 10;
UiInspectorConfig.jankFrameThresholdMs = 16.0;

Panel & Heatmap

• Call UiInspectorPanel.enable() (optional gesture: longPress or tripleTap).
• Heatmap renders automatically when UiInspectorConfig.enableHeatmap is true.

Limitations

• Debug-only: badges/panel/heatmap are inactive in release.
• Overlay order: badges/heatmap do not yet respect widget geometry (render as global overlays).
• Frame tracking requires UiInspectorConfig.trackPerformance = true.

Support

If you encounter any issues or have questions, please:

• Open an issue on GitHub
• Email: hanysameh506@gmail.com
• Check existing issues for solutions
• Review the documentation above

Show Your Support

If this package has been helpful, please consider:

• ⭐ Starring the repository on GitHub
• 🐛 Reporting bugs or suggesting features
• 📖 Sharing with other Flutter developers
• 💬 Providing feedback and improvements

License

MIT License (see LICENSE).