Widgets To Image #

A powerful Flutter package to convert any widget into high-quality images with customizable formats, quality settings, and advanced features.

🌐 Live Demo #

Try the interactive demo →

Experience the package capabilities with our modern, professional demo featuring:

• 🎯 Basic widget capture examples
• ⚙️ Advanced configuration options
• 🎭 Animation capture demonstrations
• 📱 Responsive design with Material 3

✨ Features #

• 🎯 Simple API - Convert any widget to image with just a few lines of code
• 🖼️ Multiple Formats - Support for PNG, JPEG, Raw RGBA, and Raw Unmodified formats
• ⚙️ Customizable Options - Control pixel ratio, quality, animations, and delays
• 🎨 High Quality - Generate high-resolution images with custom pixel ratios
• 🔄 Animation Support - Capture animated widgets with proper timing
• 📱 Cross Platform - Works on iOS, Android, Web, macOS, Windows, and Linux
• 🧪 Well Tested - Comprehensive test suite ensuring reliability
• 📚 Rich Documentation - Detailed examples and API documentation

🚀 Getting Started #

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  widgets_to_image: ^2.0.0

Install it using the command line:

flutter pub get

Import the package:

import 'package:widgets_to_image/widgets_to_image.dart';

📖 Usage #

Basic Usage #

// Create a controller
WidgetsToImageController controller = WidgetsToImageController();

// Wrap your widget
WidgetsToImage(
  controller: controller,
  child: Container(
    width: 200,
    height: 100,
    color: Colors.blue,
    child: const Center(
      child: Text(
        'Hello World!',
        style: TextStyle(color: Colors.white, fontSize: 20),
      ),
    ),
  ),
)

// Capture the widget
Uint8List? bytes = await controller.capture();

Advanced Usage with Options #

// Capture with custom options
Uint8List? bytes = await controller.capture(
  options: const CaptureOptions(
    format: ImageFormat.jpeg,
    pixelRatio: 3.0,
    quality: 95,
    waitForAnimations: true,
    delayMs: 100,
  ),
);

Convenience Methods #

// Capture as PNG with high resolution
Uint8List? pngBytes = await controller.capturePng(
  pixelRatio: 3.0,
  waitForAnimations: true,
);

// Capture as JPEG with custom quality
Uint8List? jpegBytes = await controller.captureJpeg(
  quality: 90,
  pixelRatio: 2.0,
);

Reactive UI with Builder #

WidgetsToImageBuilder(
  controller: controller,
  builder: (context, isCapturing, capture) {
    return Column(
      children: [
        if (isCapturing)
          const CircularProgressIndicator()
        else
          ElevatedButton(
            onPressed: () async {
              final bytes = await capture();
              // Handle the captured bytes
            },
            child: const Text('Capture Widget'),
          ),
      ],
    );
  },
)

Error Handling #

try {
  final bytes = await controller.capture();
  // Success - use the bytes
} on CaptureException catch (e) {
  // Handle specific capture errors
  print('Capture failed: ${e.message}');
  if (e.originalError != null) {
    print('Caused by: ${e.originalError}');
  }
} catch (e) {
  // Handle other errors
  print('Unexpected error: $e');
}

Lifecycle Callbacks #

controller.onCaptureStart = () {
  print('Capture started');
};

controller.onCaptureComplete = (bytes) {
  print('Capture completed with ${bytes.length} bytes');
};

controller.onCaptureError = (error) {
  print('Capture failed: ${error.message}');
};

🔧 API Reference #

CaptureOptions #

ImageFormat #

• ImageFormat.png - PNG format with transparency support
• ImageFormat.jpeg - JPEG format with quality control
• ImageFormat.rawRgba - Raw RGBA pixel data
• ImageFormat.rawUnmodified - Raw unmodified pixel data

WidgetsToImageController Methods #

• capture({CaptureOptions options}) - Capture with custom options
• capturePng({...}) - Convenience method for PNG capture
• captureJpeg({...}) - Convenience method for JPEG capture
• dispose() - Clean up resources

WidgetsToImage Properties #

• controller - The capture controller (required)
• child - The widget to capture
• clipBehavior - Whether to clip the child widget

📱 Example App #

The package includes a comprehensive example app demonstrating:

• Basic widget capture
• Advanced options configuration
• Animated widget capture
• Different image formats
• Error handling
• Reactive UI updates

Run the example:

cd example
flutter run

🛠️ Platform Support #

🤝 Contributing #

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments #

• Flutter team for the amazing framework
• Community contributors for feedback and improvements

📞 Support #

• 🐛 Report bugs
• 💡 Request features
• 📚 Documentation
• 💬 Discussions

Made with ❤️ by Mohamed Abdo

MacOS #