buoy_image_overlay

Compare a reference image with your app using placement, opacity, and tagged widget targets.

Requirements

Use a Flutter debug build and a Free or Pro Buoy account key. These packages require Dart 3.9 or later, below 4.0, and Flutter 3.27 or later; your Flutter installation must satisfy both constraints. The Buoy widget does not start its tools in profile or release builds, including with Pro.

Install and register

flutter pub add buoy_image_overlay

This example registers the standalone package. In an existing app, keep your screens and providers and apply the registration and builder changes to that app. Complete the tool-specific integration below before testing capture.

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

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  if (kDebugMode) registerBuoyImageOverlay();
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, child) => BuoyDevTools(
        licenseKey: const String.fromEnvironment('BUOY_KEY'),
        child: child ?? const SizedBox.shrink(),
      ),
      home: const Scaffold(body: Center(child: Text('Buoy test app'))),
    );
  }
}

Get a key from your Buoy account, then run:

flutter run --dart-define=BUOY_KEY=YOUR_LICENSE_KEY

If you already use the buoy umbrella, it registers the panel; keep its builder and complete the app integration below. For a complete umbrella setup, see the Flutter Quick Start.

Image sources and targets

Load an HTTP(S) image URL or a base64 data URI. Clipboard paste reads text containing a URL or data URI; it does not paste image bytes.

For Component Match, wrap an existing widget after importing this package:

BuoyImageTarget(
  label: 'ProfileCard',
  child: const Text('Test profile'),
)

Free Placement supports dragging, resizing, opacity, flips, and a position lock. Component Match aligns to tagged widgets, with scale and offset controls. Auto Track re-measures targets; check fast animation and scrolling on the device.

The overlay uses BuoyOverlayHost and keeps session state that resets on restart. This tool has no desktop-sync adapter.

Check the integration

Load a direct image URL, adjust opacity, and align it with a known widget. Scroll the screen and check alignment when Auto Track is enabled.

Full Image Overlay guide

License

Proprietary software. © Buoy LLC. See the Terms of Service and pricing.

Libraries

buoy_image_overlay