ky_guide Guide

A comprehensive and customizable onboarding system for Flutter applications that guides users through new features using beautiful overlays and tooltips.

✨ Features

🎯 Target Any Widget - Highlight any existing widget in your app
🎨 Highly Customizable - Custom colors, content, and styling
📱 Responsive Design - Automatically adapts to different screen sizes
🔄 Smart Positioning - Tooltips position themselves optimally
⏭️ Skip Functionality - Users can skip onboarding anytime
🎭 Beautiful Animations - Smooth transitions between steps
🧩 Easy Integration - Works with existing apps without major changes
🚀 Lightweight - Minimal performance impact

📱 Screenshots

Welcome Step	Feature Highlight	Custom Content

🚀 Getting Started

Installation

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

dependencies:
  ky_guide: ^0.1.0

Then run:

flutter pub get

Import

import 'package:ky_guide/ky_guide.dart';

💡 Quick Start

1. Create an GuideController

class MyHomePage extends StatefulWidget {
  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final GuideController _GuideController = GuideController();
}

2. Wrap Target Widgets

// Create GlobalKeys for your target widgets
final GlobalKey _fabKey = GlobalKey();
final GlobalKey _menuKey = GlobalKey();

// Wrap widgets you want to highlight
GuideTarget(
  onboardingKey: _fabKey,
  child: FloatingActionButton(
    onPressed: () {},
    child: Icon(Icons.add),
  ),
)

3. Create Guide Steps

void _startGuide() {
  final steps = [
    GuideStep(
      targetKey: _fabKey,
      title: 'Create New Items',
      description: 'Tap this button to create new content.',
    ),
    GuideStep(
      targetKey: _menuKey,
      title: 'Access Menu',
      description: 'Find more options in this menu.',
      backgroundColor: Colors.blue.shade50,
    ),
  ];

  _GuideController.startGuide(steps);
}

4. Start Guide

@override
void initState() {
  super.initState();
  
  // Start onboarding after first frame
  WidgetsBinding.instance.addPostFrameCallback((_) {
    _startGuide();
  });
}

🎨 Customization

Custom Step Content

GuideStep(
  targetKey: _buttonKey,
  title: 'Pro Feature',
  description: 'This is a premium feature.',
  customContent: Container(
    padding: EdgeInsets.all(12),
    decoration: BoxDecoration(
      color: Colors.amber.shade100,
      borderRadius: BorderRadius.circular(8),
    ),
    child: Row(
      children: [
        Icon(Icons.star, color: Colors.amber),
        SizedBox(width: 8),
        Text('Unlock with Pro!'),
      ],
    ),
  ),
  backgroundColor: Colors.white,
  showSkipButton: false, // Force users to see this step
)

Styling Options

GuideStep(
  targetKey: _targetKey,
  title: 'Custom Style',
  description: 'This step has custom styling.',
  tooltipPadding: EdgeInsets.all(20),
  backgroundColor: Colors.deepPurple.shade50,
  borderRadius: 12.0,
)

🎮 Controller Methods

Method	Description
`startGuide(List<GuideStep> steps)`	Start onboarding with given steps
`nextStep()`	Move to next step
`previousStep()`	Move to previous step
`skipGuide()`	Skip entire onboarding
`finishGuide()`	Complete onboarding

🎯 GuideStep Properties

Property	Type	Default	Description
`targetKey`	`GlobalKey`	Required	Key of widget to highlight
`title`	`String`	Required	Title text
`description`	`String`	Required	Description text
`customContent`	`Widget?`	`null`	Additional custom content
`tooltipPadding`	`EdgeInsets`	`EdgeInsets.all(16)`	Tooltip padding
`backgroundColor`	`Color?`	`null`	Tooltip background color
`borderRadius`	`double`	`8.0`	Highlight border radius
`showSkipButton`	`bool`	`true`	Show/hide skip button

🔧 Advanced Usage

Listen to Guide State

_GuideController.addListener(() {
  if (!_GuideController.isActive) {
    print('Guide completed!');
    // Save completion state, show celebration, etc.
  }
});

Conditional Steps

void _createConditionalGuide() {
  List<GuideStep> steps = [
    // Always show welcome
    GuideStep(
      targetKey: _welcomeKey,
      title: 'Welcome!',
      description: 'Let\'s get started.',
    ),
  ];

  // Add premium feature step only for pro users
  if (user.isPro) {
    steps.add(GuideStep(
      targetKey: _proFeatureKey,
      title: 'Pro Feature',
      description: 'This is available for pro users.',
    ));
  }

  _GuideController.startGuide(steps);
}

Multiple Guide Flows

class GuideManager {
  static const String FIRST_LAUNCH = 'first_launch';
  static const String NEW_FEATURE = 'new_feature_v2';
  
  static void showAppropriateGuide(BuildContext context) {
    final prefs = SharedPreferences.getInstance();
    
    if (!prefs.getBool(FIRST_LAUNCH, false)) {
      _showFirstLaunchGuide();
      prefs.setBool(FIRST_LAUNCH, true);
    } else if (!prefs.getBool(NEW_FEATURE, false)) {
      _showNewFeatureGuide();
      prefs.setBool(NEW_FEATURE, true);
    }
  }
}

🧪 Testing

import 'package:flutter_test/flutter_test.dart';
import 'package:ky_guide/ky_guide.dart';

void main() {
  group('GuideController', () {
    late GuideController controller;

    setUp(() {
      controller = GuideController();
    });

    test('should start with inactive state', () {
      expect(controller.isActive, false);
      expect(controller.currentStep, 0);
    });

    test('should activate when starting onboarding', () {
      final steps = [
        GuideStep(
          targetKey: GlobalKey(),
          title: 'Test',
          description: 'Test description',
        ),
      ];
      
      controller.startGuide(steps);
      expect(controller.isActive, true);
    });
  });
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for your changes
Ensure tests pass (flutter test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📋 Requirements

Flutter SDK: >=3.0.0 <4.0.0
Dart SDK: >=2.17.0 <4.0.0

🐛 Issues

If you encounter any issues, please file them on the GitHub issue tracker.

📄 License

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

🙏 Acknowledgments

Inspired by various onboarding libraries across different platforms
Thanks to the Flutter community for feedback and contributions
Special thanks to all contributors

introduction_screen - Full-screen onboarding
showcaseview - Feature showcasing
tutorial_coach_mark - Tutorial overlay

Made with ❤️ by Your Name


---

## 📄 CHANGELOG.md

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.0.0] - 2024-06-12

### 🎉 Initial Release

#### Added
- ✨ Complete onboarding system with overlay and tooltips
- 🎯 `GuideController` for managing onboarding flow
- 📝 `GuideStep` model for defining onboarding steps
- 🎨 `GuideTarget` widget for marking target elements
- 🔄 Navigation between steps (next, previous, skip, finish)
- 📱 Responsive tooltip positioning
- 🎨 Customizable styling (colors, padding, border radius)
- 📖 Custom content support for steps
- ⏭️ Configurable skip button per step
- 🌗 Dark overlay with spotlight effect on target widgets
- 📚 Comprehensive API documentation
- 🧪 Example implementation
- 🔧 TypeScript-like documentation with examples

#### Features
- **Smart Positioning**: Tooltips automatically position above or below targets
- **Customizable Content**: Add custom widgets to any step
- **Skip Functionality**: Allow users to skip onboarding entirely
- **Step Control**: Navigate forward, backward, or jump to finish
- **Responsive Design**: Works on all screen sizes
- **Easy Integration**: Minimal code changes to existing apps
- **Performance Optimized**: Efficient overlay rendering and updates

#### Developer Experience
- 📖 Complete API documentation with examples
- 🎯 Type-safe implementation
- 🧩 Easy integration with existing Flutter apps
- 🔧 Highly customizable and extensible
- 📱 Works with any existing Flutter widgets

### 📋 Requirements
- Flutter: `>=3.0.0 <4.0.0`
- Dart: `>=2.17.0 <4.0.0`

### 🔗 Links
- [Documentation](https://pub.flutter-io.cn/documentation/ky_guide/latest/)
- [Example](https://pub.flutter-io.cn/packages/ky_guide/example)
- [GitHub Repository](https://github.com/bhangun/ky_guide)

---

## [Unreleased]

### 🚧 Planned Features
- 🎥 Animation customization options
- 🎵 Sound effects support
- 📊 Analytics integration
- 🌍 Internationalization support
- 🎨 More built-in tooltip themes
- 📱 Platform-specific adaptations
- 🔄 Gesture-based navigation
- 💾 Automatic progress persistence

### 🐛 Known Issues
- None currently reported

---

## Release Notes Format

Each release follows this structure:

### [Version] - Date

#### Added ✨
- New features and capabilities

#### Changed 🔄
- Changes to existing functionality

#### Deprecated ⚠️
- Features marked for removal

#### Removed 🗑️
- Removed features

#### Fixed 🐛
- Bug fixes and corrections

#### Security 🔒
- Security-related changes

---

**Note**: This project follows [Semantic Versioning](https://semver.org/). Given a version number MAJOR.MINOR.PATCH:
- **MAJOR** version changes for incompatible API changes
- **MINOR** version changes for backward-compatible functionality additions  
- **PATCH** version changes for backward-compatible bug fixes

🚀 Publishing Checklist

Before publishing to pub.flutter-io.cn, ensure:

All files are in correct directory structure
pubspec.yaml has correct version and metadata
README.md is comprehensive with examples
CHANGELOG.md documents all changes
LICENSE file is included
Tests are written and passing
Documentation is complete
Example app works correctly
No sensitive information in code
Package analysis passes (dart pub publish --dry-run)

📦 Publishing Command

# Dry run to check for issues
dart pub publish --dry-run

# Publish to pub.flutter-io.cn
dart pub publish

This package is now ready for publication to pub.flutter-io.cn with all the necessary files, documentation, and structure!

ky_guide Guide

✨ Features

📱 Screenshots

🚀 Getting Started

Installation

Import

💡 Quick Start

1. Create an GuideController

2. Wrap Target Widgets

3. Create Guide Steps

4. Start Guide

🎨 Customization

Custom Step Content

Styling Options

🎮 Controller Methods

🎯 GuideStep Properties

🔧 Advanced Usage

Listen to Guide State

Conditional Steps

Multiple Guide Flows

🧪 Testing

🤝 Contributing

Development Setup

📋 Requirements

🐛 Issues

📄 License

🙏 Acknowledgments

🚀 Publishing Checklist

📦 Publishing Command

Libraries

ky_guide package

ky_guide Guide

✨ Features

📱 Screenshots

🚀 Getting Started

Installation

Import

💡 Quick Start

1. Create an GuideController

2. Wrap Target Widgets

3. Create Guide Steps

4. Start Guide

🎨 Customization

Custom Step Content

Styling Options

🎮 Controller Methods

🎯 GuideStep Properties

🔧 Advanced Usage

Listen to Guide State

Conditional Steps

Multiple Guide Flows

🧪 Testing

🤝 Contributing

Development Setup

📋 Requirements

🐛 Issues

📄 License

🙏 Acknowledgments

📚 Related Packages

🚀 Publishing Checklist

📦 Publishing Command

Libraries

ky_guide package