📸 Screenshots #

✨ Features #

• 🎯 Dynamic Highlighting - Wrap any widget to highlight it with a coach mark overlay
• 🎨 Fully Customizable - Control colors, sizes, borders, shadows, and positioning
• 📱 Smart Positioning - Automatically adjusts bubble position based on available screen space
• 🧭 Position Control - Auto-detect the best position or manually specify preferred placement
• 🌗 Dimmed Overlay - Creates focus by dimming the background with a cut-out hole
• 📏 Highlight Padding - Add extra space around highlighted targets
• 🔒 Safe Area Support - Optional control over safe area behavior
• 🧩 Sequential Tours - Easily create multi-step onboarding experiences
• 🪶 Lightweight - Zero external dependencies beyond Flutter SDK
• ⚡ Simple API - Widget-based, easy to integrate

📦 Installation #

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

dependencies:
  coachmark: ^0.1.0

Then run:

flutter pub get

Latest Version: Check pub.dev for the most recent version.

🚀 Quick Start #

1. Import the Package #

import 'package:coachmark/coachmark.dart';

2. Wrap Your Widget #

Coachmark(
  isVisible: true,
  config: CoachmarkConfig(
    description: 'Tap this button to perform an action!',
  ),
  onDismiss: () {
    // Handle dismiss
  },
  child: ElevatedButton(
    onPressed: () {},
    child: Text('My Button'),
  ),
)

That's it! Your first coachmark is ready. 🎉

📚 Examples #

Basic Usage #

Show a simple coachmark on any widget:

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

class BasicExample extends StatefulWidget {
  @override
  State<BasicExample> createState() => _BasicExampleState();
}

class _BasicExampleState extends State<BasicExample> {
  bool _showCoachmark = false;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Coachmark Example')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Coachmark(
              isVisible: _showCoachmark,
              config: const CoachmarkConfig(
                description: 'Tap this button to perform an action!',
                highlightBorderColor: Colors.blue,
              ),
              onDismiss: () => setState(() => _showCoachmark = false),
              child: ElevatedButton(
                onPressed: () {
                  // Your action
                },
                child: const Text('Action Button'),
              ),
            ),
            const SizedBox(height: 20),
            TextButton(
              onPressed: () => setState(() => _showCoachmark = true),
              child: const Text('Show Coachmark'),
            ),
          ],
        ),
      ),
    );
  }
}

Custom Styling #

Create a beautifully styled coachmark:

Coachmark(
  isVisible: true,
  config: CoachmarkConfig(
    description: 'This feature helps you accomplish your goals faster!',
    descriptionStyle: const TextStyle(
      fontSize: 16,
      color: Colors.white,
      fontWeight: FontWeight.w500,
    ),
    bubbleBackgroundColor: const Color(0xFF2C3E50),
    bubbleBorderColor: Colors.blueAccent,
    highlightBorderColor: Colors.greenAccent,
    highlightBorderWidth: 3.0,
    highlightCornerRadius: 16.0,
    highlightPadding: const EdgeInsets.all(8.0), // Add space around target
    bubbleCornerRadius: 12.0,
    bubblePadding: const EdgeInsets.all(20.0),
    bubbleMaxWidth: 320.0,
    overlayColor: const Color(0xAA000000),
    spacing: 16.0,
    preferredPosition: CoachmarkBubblePosition.bottom,
    bubbleShadow: [
      BoxShadow(
        color: Colors.black.withOpacity(0.3),
        blurRadius: 20,
        offset: const Offset(0, 10),
      ),
    ],
  ),
  onDismiss: () {
    // Handle dismiss
  },
  child: YourWidget(),
)

Sequential Tour #

Create a multi-step onboarding tour:

class OnboardingTour extends StatefulWidget {
  const OnboardingTour({super.key});

  @override
  State<OnboardingTour> createState() => _OnboardingTourState();
}

class _OnboardingTourState extends State<OnboardingTour> {
  bool _showStep1 = false;
  bool _showStep2 = false;
  bool _showStep3 = false;

  void _startTour() {
    setState(() => _showStep1 = true);
  }

  void _nextStep() {
    setState(() {
      if (_showStep1) {
        _showStep1 = false;
        _showStep2 = true;
      } else if (_showStep2) {
        _showStep2 = false;
        _showStep3 = true;
      } else {
        _showStep3 = false;
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Product Tour'),
        actions: [
          IconButton(
            icon: const Icon(Icons.help_outline),
            onPressed: _startTour,
          ),
        ],
      ),
      body: Column(
        children: [
          // Step 1: Highlight a menu item
          Coachmark(
            isVisible: _showStep1,
            config: const CoachmarkConfig(
              description: '👋 Welcome! Tap the help icon to restart this tour.',
              bubbleBackgroundColor: Colors.blue,
              descriptionStyle: TextStyle(color: Colors.white),
            ),
            onDismiss: _nextStep,
            child: ListTile(
              leading: const Icon(Icons.home),
              title: const Text('Home'),
              onTap: () {},
            ),
          ),
          
          // Step 2: Highlight settings
          Coachmark(
            isVisible: _showStep2,
            config: const CoachmarkConfig(
              description: '⚙️ Access your settings here.',
              highlightBorderColor: Colors.orange,
            ),
            onDismiss: _nextStep,
            child: ListTile(
              leading: const Icon(Icons.settings),
              title: const Text('Settings'),
              onTap: () {},
            ),
          ),
          
          // Step 3: Highlight profile
          Coachmark(
            isVisible: _showStep3,
            config: const CoachmarkConfig(
              description: '👤 View and edit your profile information.',
              bubbleBackgroundColor: Colors.green,
              descriptionStyle: TextStyle(color: Colors.white),
            ),
            onDismiss: _nextStep,
            child: ListTile(
              leading: const Icon(Icons.person),
              title: const Text('Profile'),
              onTap: () {},
            ),
          ),
        ],
      ),
    );
  }
}

Highlight Padding Example #

Add space around small tap targets:

Coachmark(
  isVisible: true,
  config: const CoachmarkConfig(
    description: 'Tap here to add a new item',
    highlightPadding: EdgeInsets.all(12.0), // Expands the highlight area
    highlightBorderColor: Colors.purple,
  ),
  onDismiss: () {},
  child: IconButton(
    icon: const Icon(Icons.add),
    onPressed: () {},
  ),
)

Safe Area Control #

Control whether the bubble respects safe areas:

Coachmark(
  isVisible: true,
  config: const CoachmarkConfig(
    description: 'This bubble can draw behind the status bar',
    drawOverSafeArea: true, // Allow bubble to extend into safe areas
  ),
  onDismiss: () {},
  child: YourWidget(),
)

📖 API Reference #

Coachmark Widget #

Coachmark({
  required Widget child,
  required CoachmarkConfig config,
  bool isVisible = false,
  VoidCallback? onDismiss,
  GlobalKey? childKey,
})

CoachmarkConfig #

CoachmarkBubblePosition #

enum CoachmarkBubblePosition {
  auto,    // Automatically choose the best position
  left,    // Place bubble to the left of the target
  right,   // Place bubble to the right of the target
  top,     // Place bubble above the target
  bottom,  // Place bubble below the target
}

💡 Best Practices #

✅ Do's #

• ✅ Use sequential coachmarks to guide users through complex flows
• ✅ Keep descriptions short and actionable (under 50 words)
• ✅ Test your coachmarks on different screen sizes
• ✅ Use highlightPadding to add breathing room around small targets
• ✅ Dismiss coachmarks on user interaction for better UX
• ✅ Use GlobalKey when highlighting widgets in complex layouts

❌ Don'ts #

• ❌ Don't show too many coachmarks at once (3-5 max per tour)
• ❌ Don't block critical UI interactions with coachmarks
• ❌ Don't use tiny font sizes that are hard to read
• ❌ Don't forget to handle coachmark state properly
• ❌ Don't show the same coachmark repeatedly to returning users

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License #

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

🔗 Links #

• Repository: github.com/youseflabs-k/coachmark
• Issues: github.com/youseflabs-k/coachmark/issues
• pub.dev: pub.dev/packages/coachmark
• Example App: example/