scratch_reveal #

color=2E8B57[](https://pub.flutter-io.cn/packages/scratch_reveal/score)label=pub%20points)](https://pub.flutter-io.cn/packages/scratch_reveal/score)

A high-performance, GPU-accelerated scratch card and scratch-to-reveal canvas widget for Flutter with sub-millisecond spatial bitmask area tracking, smooth auto-reveal animations, and customizable foil styles.

⚡ Why scratch_reveal? #

Existing scratch card packages on pub.flutter-io.cn suffer from a fundamental architectural flaw: they calculate scratch coverage by reading raw bitmap pixels out of CPU image buffers on every drag stroke, causing micro-stutters and frame drops.

scratch_reveal solves this with a 2D Spatial Bitmask Grid Engine:

1. Sub-0.1ms Progress Calculation: Calculates the exact percentage scratched instantly without querying GPU memory or freezing the UI thread.
2. GPU BlendMode.clear Pipeline: Buttery smooth 120 FPS eraser strokes on high-refresh-rate mobile devices.
3. Threshold Auto-Reveal & Animations: Smoothly fades/scales out remaining foil once the target threshold (e.g. 60%) is reached.
4. Rich Styling: Solid colors, multi-stop metallic gradients (silver/gold foil), or custom widget overlays.
5. Zero Native C++: 100% pure Flutter & Dart across iOS, Android, Web, macOS, Windows, and Linux.

📦 Installation #

Add scratch_reveal to your pubspec.yaml:

dependencies:
  scratch_reveal: ^1.1.1

Or run:

flutter pub add scratch_reveal

🚀 Quick Start #

1. Metallic Foil Scratch Card with Auto-Reveal #

import 'package:flutter/material.dart';
import 'package:scratch_reveal/scratch_reveal.dart';

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

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 320,
      height: 180,
      child: ClipRRect(
        borderRadius: BorderRadius.circular(20),
        child: ScratchReveal(
          brushSize: 40.0,
          threshold: 0.65, // Auto-reveals at 65% scratched
          coverGradient: const LinearGradient(
            colors: [Color(0xFFE2E8F0), Color(0xFF94A3B8), Color(0xFF475569)],
          ),
          cover: const Center(
            child: Text('SCRATCH TO REVEAL', style: TextStyle(fontWeight: FontWeight.bold, color: Colors.white)),
          ),
          revealedChild: Container(
            color: const Color(0xFFD97706),
            alignment: Alignment.center,
            child: const Text('🎉 ₹500 VOUCHER CODE: LUCKY2026', style: TextStyle(color: Colors.white, fontSize: 16)),
          ),
          onThresholdReached: () {
            print('Reward unlocked!');
          },
          onProgressUpdate: (progress) {
            print('Progress: ${(progress * 100).toInt()}%');
          },
        ),
      ),
    );
  }
}

2. Programmatic Reveal & Reset #

final scratchKey = GlobalKey<ScratchRevealState>();

// Reset the card back to unscratched:
scratchKey.currentState?.reset();

// Automatically reveal the reward:
scratchKey.currentState?.reveal();

🛠️ API Reference #

ScratchReveal Properties #

💖 Support the Project #

If you find this project useful, consider supporting its active maintenance and future development:

📄 License #

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

Maintained with ❤️ by Govind Tank.